Skip to content
Log in
  • There are no suggestions because the search field is empty.

Connect API Access

 Summary

The API Access module lets your developers connect their systems directly to the Plumm API. Use it to browse available endpoints, try requests in a live playground, manage API keys, whitelist trusted IP addresses, and enable or disable the integration , all from one place.

This guide walks you through every tab and setting, step by step.

In this article

  • Before you begin
  • Step 1: Open the API Access module
  • Step 2: Review the Overview
  • Step 3: Explore Endpoints
  • Step 4: Try requests in the Playground
  • Step 5: Understand Rate Limiting
  • Step 6: Create and manage API Keys
  • Step 7: Configure Settings (IP whitelist & integration toggle)
  • Frequently Asked Questions (FAQ)

Before you begin

Only Plumm system administrators (or users with the Developer role) can set up and manage API Access.

You'll need:

  • A Plumm admin account for your company
  • The public IPv4 address(es) of the server(s) that will call the Plumm API (up to 3 per company)
  • A secure place to store the generated API key (a secrets manager or.envfile — never commit it to source control)

Step 1. Open the API Access module

  1. Log in to your Plumm dashboard.
  2. From the navigation menu in the top-left corner, go to Tech.
  3. Under Tech, select API Access.
  4. You will land on the Overview tab by default.

Step 2. Review the Overview

The Overview tab is your starting point. It gives you a short summary of what the Plumm API can do and links to the other tabs. You'll find the base URL for every request on the Overview tab inside the API Access module.

Use this tab to orient new developers on your team before they start integrating.

Step 3. Explore Endpoints

Open the Endpoints tab to browse every endpoint available in the Plumm API.

  1. Each endpoint card shows the HTTP method (GET, POST, PUT, DELETE), the path, and a short description.
  2. Click an endpoint to expand it and see required and optional parameters, the request body schema (where applicable), an example response, and possible error codes.
  3. Use the search box at the top to filter endpoints by name or path.

Endpoints are grouped by resource (People, Time Off, Payroll, Documents, etc.) so you can quickly find what you need.

Step 4. Try requests in the Playground

The Playground tab lets you send real API requests without writing any code.

  1. Select the endpoint you want to test from the dropdown.
  2. Fill in the required parameters and (if applicable) the request body.
  3. Choose which API key to authenticate with  a test key is recommended while exploring.
  4. Click Send request.
  5. Review the response, status code, and headers in the panel on the right.

Tip: Use the Playground to validate payloads before wiring the call into your application.

Step 5. Understand Rate Limiting

The Plumm API uses a sliding-window rate limiter. Every response includes headers showing your current consumption.

  • The Plumm API supports a maximum of 60 requests in 60 seconds per customer.
  • If you exceed the limit, the API returns HTTP 429 Too Many Requests with a JSON error body:
{   "error": "rate_limit_exceeded",   "message": "You have exceeded 60 requests in 60 seconds.",   "retry_after": 12 }

Wait for the number of seconds shown in retry_after before retrying. If you need a higher limit, contact your Plumm account manager.

Step 6. Create and manage API Keys

Open the API Keys tab to generate the credentials your application will use.

  1. Click Create key.
  2. Give the key a memorable name (for example, production-server).
  3. Choose the environment Test or Live.
  4. Click Generate.
  5. Copy the key immediately and store it in a secure secrets manager. The full key is shown only once, after you close the dialog, only the last four characters are visible.
  6. To revoke a key, click the trash icon next to it. Revocation is instant.

Important: Only one API key can be active per company at any time. Creating a new key will require you to revoke the existing one first.

Step 7. Configure Settings

The Settings tab controls two things: which IP addresses may call the API on your behalf, and whether the integration is enabled at all.

7a. IP address whitelisting

  1. Under Whitelisted IP addresses, enter the public IPv4 address you want to allow.
  2. Add an optional label (for example, Prod app server) to help you recognise it later.
  3. Click Add IP.
  4. Repeat for each address, you can whitelist up to 3 IPs per company.
  5. To remove an IP, click the trash icon next to it.

Any request that comes from an IP not on this list is rejected with HTTP 403 Forbidden.

7b. Enable / disable the integration

At the top of the Settings tab you'll see an Integration status toggle.

  • Enabled (default): the API accepts requests from your whitelisted IPs.
  • Disabled: every request from any IP, using any key  is rejected with HTTP 403 Forbidden. A warning banner will appear on the Settings page while the integration is disabled.

Use the toggle as an emergency "kill switch" if you suspect a key has leaked, or during maintenance windows.

Frequently Asked Questions (FAQ)

1. Who can set up API Access?

Only Plumm system administrators or users with the Developer role.

2. How many API keys can be active at once?

Only one API key can be active per company at any time. Revoke the current key before generating a new one.

3. How many IP addresses can I whitelist?

Up to 3 IPv4 addresses (or CIDR ranges) per company.

4. What happens if a request comes from an IP that isn't whitelisted?

The API returns 403 Forbidden and the request never reaches your data.

5. What is the rate limit?

60 requests in 60 seconds per customer. Exceeding it returns 429 Too Many Requests with a retry_after value in seconds.

6. What happens when I disable the integration?

All API requests are immediately rejected with 403 Forbidden, regardless of the key or source IP. Re-enable the toggle to resume access.

7. I lost my API key  can I retrieve it?

No. The full key is shown only once, at creation time. If you've lost it, revoke the old key and generate a new one.

8. Can I test the API without affecting live data?

Yes. Create a Test environment key and use it in the Playground or from your own client. Test keys are sandboxed and never touch production data.