A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Deel API is how an app or AI agent works with a Deel organization: listing people, creating and signing contracts, submitting time off and timesheets, and reading invoices, payments, and payslips. Access is granted through an API token or an OAuth 2.0 token, and OAuth scopes in a resource:action shape, like people:read or contracts:write, set which areas a call can read or write. Deel pins dated API versions selected per request, and a state change can emit a signed event to a registered endpoint.
How an app or AI agent connects to Deel determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Deel tools to agents, and each is governed by the token behind it and the permissions that token carries.
The REST API takes JSON request bodies, returns JSON, and pages through lists, at https://api.letsdeel.com/rest/v2. A call authenticates with an API token sent as a Bearer token, or with an OAuth 2.0 access token. The sandbox runs at a separate host for testing.
A hosted Model Context Protocol server at https://api.letsdeel.com/mcp exposes Deel operations as tools that an AI agent can call directly. It authenticates with an OAuth 2.0 application (recommended) or a personal access token for clients without OAuth. Each tool maps to a Deel API operation, with organization-level tools (like getListOfPeople), worker-level tools (like createTimeOffRequest and getTimeOffRequests), and public reference tools (like retrieveCountries and retrieveSupportedCurrencies).
Deel POSTs a JSON event to an endpoint registered for an organization when something happens, like a contract being created. Each request carries an x-deel-signature header, an HMAC-SHA256 signature over the method and raw body computed with the endpoint's signing key, plus an x-deel-hmac-label naming the key and an x-deel-webhook-version naming the serialization version. Delivery retries with backoff up to ten attempts, and a subscription is disabled after ten consecutive failures.
A token-based credential for server-to-server integrations, sent in the Authorization header as a Bearer token. An organization token reaches all organizational resources, while a personal token is limited to resources the issuing user can access. Tokens are generated in the Developer Center of a Deel account.
The user-authorized flow for third-party apps and multi-tenant SaaS. An app requests a space-separated list of scopes such as people:read and contracts:write, the user approves them on a consent screen, and the access token carries only the granted scopes. Each request sends the access token plus an x-client-id header, and an access token expires after 30 days. Authorization runs at app.deel.com/oauth2/authorize and tokens are issued at app.deel.com/oauth2/tokens.
The Deel API is split into areas an agent can act on, like people, contracts, time off, timesheets, invoices, and payments. Each area carries its own permission, and writes in some areas create contracts, submit time off, or change worker records.
Methods for reading the people and worker records in an organization.
Methods for creating, reading, and signing contracts.
Methods for reading and submitting time-off requests.
Methods for reading and submitting timesheets.
Methods for reading invoices and creating invoice adjustments.
Methods for reading payments to Deel and downloading worker payslips.
Methods for reading the structure of an organization.
Methods for subscribing to events and listing event types.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
People & WorkersMethods for reading the people and worker records in an organization.2 | ||||||
| GET | /rest/v2/people | Return a paginated list of people in the organization, with filtering by search, team, and custom fields. | read | people:read | Current | |
Returns personal and employment data for every person the token can see. Acts onperson Permission (capability) people:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /rest/v2/people/:hris_profile_id | Return detailed information about a single person by their public profile id. | read | people:read | Current | |
The path takes the person's public profile id, not a worker id. Acts onperson Permission (capability) people:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ContractsMethods for creating, reading, and signing contracts.4 | ||||||
| POST | /rest/v2/contracts | Create a new contractor contract and return it with its assigned id. | write | contracts:write | Current | |
Creates a real contract; the contract starts before it is signed. Acts oncontract Permission (capability) contracts:writeVersionAvailable since the API’s base version Webhook event contract.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /rest/v2/contracts/:contract_id | Fetch the full record for a single contract, including status, compensation, and worker information. | read | contracts:read | Current | |
Read-only. Acts oncontract Permission (capability) contracts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /rest/v2/contracts | Return a paginated list of contract summaries, with optional filtering by status, type, team, country, currency, or name. | read | contracts:read | Current | |
Read-only. Acts oncontract Permission (capability) contracts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /rest/v2/contracts/:contract_id/signatures | Sign a contract on behalf of the client, advancing it through the hiring workflow. | write | contracts:write | Current | |
Signs as the client (employer) side of the contract. Acts oncontract_signature Permission (capability) contracts:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Time offMethods for reading and submitting time-off requests.2 | ||||||
| GET | /rest/v2/time_offs | Return the time-off requests for the authenticated organization. | read | time-off:read | Current | |
The path uses an underscore (time_offs); the scope uses a hyphen (time-off:read). Acts ontime_off Permission (capability) time-off:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /rest/v2/time_offs | Create a new time-off request for a worker. | write | time-off:write | Current | |
Also requires the worker:write scope alongside time-off:write. Acts ontime_off Permission (capability) time-off:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TimesheetsMethods for reading and submitting timesheets.2 | ||||||
| GET | /rest/v2/timesheets | Return a paginated list of timesheets, with filtering by contract, type, status, reporter, and date range. | read | timesheets:read | Current | |
Read-only. Acts ontimesheet Permission (capability) timesheets:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /rest/v2/timesheets | Create a timesheet entry, submitting work for a contractor. | write | timesheets:write | Current | |
Submitted work can feed a contractor invoice or payment. Acts ontimesheet Permission (capability) timesheets:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Invoices & adjustmentsMethods for reading invoices and creating invoice adjustments.4 | ||||||
| GET | /rest/v2/invoices | Return a paginated list of invoices, paid by default and all statuses when requested. | read | accounting:read | Current | |
Read-only. Acts oninvoice Permission (capability) accounting:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /rest/v2/invoices/deel | Return a paginated list of invoices for Deel platform fees. | read | accounting:read | Current | |
Read-only. Acts oninvoice Permission (capability) accounting:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /rest/v2/invoice-adjustments | Create an invoice adjustment, such as a bonus, expense, or deduction line. | write | invoice-adjustments:write | Current | |
Also requires the worker:write scope alongside invoice-adjustments:write. Acts oninvoice_adjustment Permission (capability) invoice-adjustments:writeVersionAvailable since the API’s base version Webhook event invoice-adjustment.reviewedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /rest/v2/contracts/:contract_id/invoice-adjustments | Return the invoice adjustments for a contract. | read | invoice-adjustments:read | Current | |
Read-only. Acts oninvoice_adjustment Permission (capability) invoice-adjustments:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Payments & payslipsMethods for reading payments to Deel and downloading worker payslips.3 | ||||||
| GET | /rest/v2/payments | Return a cursor-paginated list of payments made to Deel, with worker details, status, and methods. | read | accounting:read | Current | |
Read-only. Acts onpayment Permission (capability) accounting:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /rest/v2/eor/workers/:worker_id/payslips/:payslip_id/download | Return a URL for downloading the specified employer-of-record payslip as a PDF. | read | payslips:read | Current | |
Returns a downloadable payslip document for an employer-of-record worker. Acts onpayslip Permission (capability) payslips:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /rest/v2/gp/workers/:id/payslips | Return the payslip history for a global-payroll employee. | read | payslips:read | Current | |
The path takes the worker's id directly. Acts onpayslip Permission (capability) payslips:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationsMethods for reading the structure of an organization.3 | ||||||
| GET | /rest/v2/legal-entities | Return the list of legal entities in the organization. | read | organizations:read | Current | |
Read-only. Acts onlegal_entity Permission (capability) organizations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /rest/v2/teams | Return the list of teams within the authenticated organization. | read | organizations:read | Current | |
Read-only. Acts onteam Permission (capability) organizations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /rest/v2/departments | Return the list of departments in the organization, with id, name, and parent. | read | organizations:read | Current | |
Read-only. Acts ondepartment Permission (capability) organizations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksMethods for subscribing to events and listing event types.2 | ||||||
| GET | /rest/v2/webhooks/events/types | Retrieve the list of webhook event types an organization can subscribe to. | read | — | Current | |
Deel does not publish a static event list; this method enumerates the current event types. Acts onwebhook_event_type Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /rest/v2/webhooks | Create a webhook subscription that delivers chosen events to an endpoint. | write | — | Current | |
Sets which events are delivered and where; the reference page does not state a scope. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Deel can notify an app when something happens in an account, like a contract being created or an invoice adjustment being approved. It sends a signed HTTP request describing what changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
contract.created | A contract was created in the organization. Event names follow a resource.action shape, like contract.created. | /rest/v2/contracts |
invoice-adjustment.reviewed | An invoice adjustment was reviewed and approved. | /rest/v2/invoice-adjustments |
Deel limits how fast an app can call, by a request rate measured per second and shared across the whole organization.
Deel meters requests by rate, not by a per-method cost. The limit is five requests per second, measured across the whole organization and shared by every token in it, on a rolling one-second window. Deel does not return rate-limit headers, so an integration has to track its own pace, queue requests, and space out anything it would otherwise send in a burst. Going over returns HTTP 429 until the next window starts.
List endpoints are paginated. Many take limit and offset query parameters to page through results, while some newer endpoints, like payments, use cursor-based pagination. A response signals whether more pages remain so an integration can keep fetching until the list is exhausted.
An OAuth access token expires 30 days after it is issued and must be refreshed before then. A dated API version stays usable until its sunset date, and a deprecated version keeps working for one year before it returns 410.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | The request was malformed or failed validation, for example a missing field or an unrecognized API version. Deel surfaces validation failures as 400 rather than 422. | Read the error message, fix the request body or parameters, and resend. The request is not retryable as-is. |
| 401 | unauthorized | No valid credential was provided. For OAuth, this also occurs when the Authorization header or the x-client-id header is missing. | Send a valid API token or OAuth access token, and include x-client-id on OAuth requests. |
| 403 | forbidden | The credential is valid but lacks the scope or permission the request needs. | Grant the required scope on the token, such as people:read, then retry. |
| 404 | not_found | The requested object does not exist or is not visible to this credential. | Verify the id and confirm the object belongs to the same organization. |
| 410 | gone | The requested dated API version has reached its sunset. The body returns latest_stable_version and sunset_date. | Move to the version named in latest_stable_version using the X-Version header. |
| 429 | too_many_requests | The organization-wide rate limit was exceeded. Deel does not return rate-limit headers. | Queue and space requests to stay under five per second, then retry once the window resets. |
| 500 | internal_server_error | An error on Deel's side. It is rare. | Retry with backoff, and contact Deel support if it persists. |
Deel uses dated API versions, selected per request, with a baseline version that stays stable for a year and a lifecycle that marks each version beta, stable, or deprecated.
Deel pins API versions to dates in a YYYY-MM-DD format, selected per request with the X-Version header. The 2026-01-01 baseline applies to existing endpoints and stays stable until at least January 2027. Responses carry an X-State header marking each version beta, stable, or deprecated, and a sunset version returns 410 with the latest stable version named.
Additive changelog updates, delivered without minting a new baseline version.
Additive changelog updates across HR and accounting resources.
Additive changelog updates earlier in the year.
Pin a dated version with a request header and move up on a schedule that suits the integration.
Deel API changelog ↗Bollard AI sits between a team's AI agents and Deel. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.