View in Help Center/New Window
Overview: The Buddy Punch Developer API lets you connect your own software to Buddy Punch to read and manage employees, punches, time entries, time off, schedules, and more - so you can automate data syncs, build custom reports, or integrate Buddy Punch with the other tools your team uses.
This guide is for account Administrators and walks you through enabling the API, creating an API key with the right permissions, and making your first authenticated request.
Important: The new Developer API is served from api2.buddypunch.com.
Instructions:
Before you begin
You'll need two things in place:
You're signed in as an Administrator on the Buddy Punch account. (Managers and employees can't create API keys.)
The Developer API is enabled on your account. If you don't see it under Settings --> Integrations, reach out to our support team, and we'll turn it on for you.
Step 1: Log in to Buddy Punch as an Administrator, then go to Settings --> Integrations. Search for or scroll to the Developer API card and click the blue Manage API Keys button:
Step 2: The API Keys page lists any keys you've already created, along with each key's name, key prefix, permissions, status, last-used date, and creation date. From here, click + Create New API Key:
Step 3: Give your key a clear Key Name (for example, "Production Integration") so you can recognize it later. Then set the Permissions for the key.
Each resource can be granted Read and/or Write access. Use Select All (Full Access) to grant everything, or check only the specific resources your integration needs. As a best practice, grant the smallest set of permissions your integration actually requires - you can always create another key later if your needs grow:
Step 4: After you create the key, the full API key is shown only once. Copy it immediately and store it somewhere secure - you won't be able to view it again. If you lose a key, simply revoke it from the API Keys page and create a new one.
Important! Keep your key secure!
Treat your API key like a password - anyone with it can access your account's data within the key's permissions.
Store it in a secrets manager or environment variable; never hard-code it into client-side or shared code.
Use separate keys for separate integrations so you can revoke one without disrupting the others.
Revoke any key that's no longer used or may have been exposed, and create a replacement.
Using your API key
Base URL
All requests go to:
https://api2.buddypunch.com
Authentication
Every request must include your API key as a Bearer token in the Authorization request header, in the form Authorization: Bearer YOUR_API_KEY. Ready-to-run request examples in curl, Node.js, Python, and C# are available in the interactive documentation (linked at the bottom of this article).
If the key is missing or invalid, you'll receive a 401 response. If the key is valid but lacks the permission scope an endpoint requires, you'll receive a 403.
API versioning
Pin a version by sending an X-Api-Version header (for example, X-Api-Version: 2025-03-01) so your integration keeps working when newer versions ship. Watch the Changelog in the documentation for breaking changes.
Permission scopes
Each API key carries a set of scopes in the form {resource}:read or {resource}:write. A request is rejected with a 403 if the key lacks the scope the endpoint requires.
Available scopes include:
Resource | Read scope | Write scope |
Employees | employees:read | employees:write |
Punches | punches:read | punches:write |
Time Entries | timeentries:read | timeentries:write |
Time Off | pto:read | pto:write |
Time Cards | timecards:read | timecards:write |
Pay Periods | payperiods:read | payperiods:write |
Locations | locations:read | locations:write |
Department Codes | departmentcodes:read | departmentcodes:write |
Positions | positions:read | positions:write |
Groups | groups:read | groups:write |
Geofences | geofences:read | geofences:write |
Webhooks | webhooks:read | webhooks:write |
Pagination
List endpoints use cursor-based pagination. Use limit (1–100, default 25) to control page size, and startingAfter / endingBefore with an item ID as a cursor. Responses are wrapped in an envelope:
{
"object": "list",
"data": [ ... ],
"hasMore": true,
"totalCount": 142,
"url": "/employee"
}
Rate limits
Per-minute rate limits are applied per account using a sliding window, and the ceiling depends on your Buddy Punch plan:
Plan tier | Per-account limit |
Trial/non-paying | 60 requests/minute |
Paid non-Enterprise (Starter / Pro ) | 600 requests/minute |
Enterprise | 1,000 requests/minute |
When you hit a limit, you'll get a 429 Too Many Requests response. Check the Retry-After header for how many seconds to wait, then retry - and back off exponentially on repeated failures. Trial accounts also have additional per-resource caps, daily write caps, and a one-active-key limit.
Errors
All errors follow a consistent JSON envelope:
{
"error": {
"type": "invalid_request_error",
"code": "resource_not_found",
"message": "Employee 999 not found.",
"requestId": "req_abc123"
}
}Status | Type | Meaning |
400 | invalid_request_error | Missing or invalid parameters |
401 | authentication_error | Invalid or missing API key |
403 | authorization_error | Key lacks the required permission scope |
404 | invalid_request_error | Resource not found |
409 | invalid_request_error | Idempotency conflict |
429 | rate_limit_error | Rate limit exceeded |
500 | api_error | Internal server error |
Include the requestId from an error response when contacting support - it helps us track down what happened.
Full API documentation
Complete, interactive documentation - including every endpoint, the full data model, idempotency, webhooks, code examples (curl, Node.js, Python, C#), and the migration guide for moving off the legacy API - is available at: https://api2.buddypunch.com/docs/