From deel-api
Deel REST API integration reference. Use when building features that sync data from Deel, working on the Deel integration module, or troubleshooting Deel API calls (people, organizations, teams, departments, time-off, contracts, lookups).
How this skill is triggered — by the user, by Claude, or both
Slash command
/deel-api:deel-apiThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this guide when building an app that integrates with the Deel REST API, in any tech stack.
Use this guide when building an app that integrates with the Deel REST API, in any tech stack.
| Property | Value |
|---|---|
| Base URL (Production) | https://api.letsdeel.com/rest/v2 |
| Base URL (Sandbox) | https://api-sandbox.demo.deel.com/rest/v2 |
| Auth | Authorization: Bearer <DEEL_API_KEY> header |
| Content Type | application/json |
| Protocol | HTTPS only (HTTP will fail) |
| Pagination | Cursor-based: pass ?limit=N&after_cursor=CURSOR |
| Response shape | { "data": [...], "page": { "cursor": "...", "total_rows": N } } |
| Rate limits | ~100 requests/minute observed (applies to sandbox too) |
The DEEL_API_KEY is a JWT. Before building any routes, decode the JWT payload to check the scope field. Only build routes for scopes the token has.
Token types:
Critical JWT flags that affect response shape:
| JWT Field | Effect |
|---|---|
scope | Determines which endpoints return 200 vs 403 |
hide_pii_data | If true, personal emails and birth dates may be redacted |
hide_employment_data | If true, employment fields (job_title, hiring_type, hiring_status, department, country, start_date, timezone) are nested in employments[] |
Important: Always check hide_employment_data in your token. When true, you must read employment fields from person.employments[0] (the active employment), not from the person root object.
| Scope | Endpoints |
|---|---|
people:read | /people, /people/:id, /people/custom_fields |
organizations:read | /organizations, /hris/organization_structures, /legal-entities, /managers |
groups:read | /teams, /departments |
time-off:read | /time_offs, /time_offs/profile/:id, /time_offs/profile/:id/entitlements |
contracts:read | /contracts, /contracts/:id, /contract-templates |
| (none) | /lookups/countries, /lookups/currencies, /lookups/job-titles, /lookups/seniorities, /lookups/time-off-types |
scope tells you which endpoints return 200 vs 403api-sandbox.demo.deel.com, not api.letsdeel.com. A sandbox token against production returns 401hide_employment_data changes response shape — fields like job_title, department move into employments[0]after_cursor from page.cursor, not page numbershris_organization_user_id — not the person UUID or worker_id/time_offs list does NOT support limit — passing it returns 400:id is a short alphanumeric string (e.g. 5dkw6zv), not a UUIDperson.emails.find(e => e.type === 'work')?.value/custom-fields before /:id/time_offs vs /lookups/time-off-typesLast updated: 2026-03-02 by Franklin Lee
npx claudepluginhub andershalo/halo-ai-dev-tools --plugin deel-apiAutomates Deel operations (contractor payments, compliance) via Composio's Deel toolkit through Rube MCP. Always searches for current tool schemas before execution.
Automates BambooHR HR tasks like listing/searching employees, tracking changes, managing time-off via Rube MCP and Composio toolkit. Requires active connection; search tools first for schemas.
Automates BambooHR HR operations like employee directories, changes tracking, time-off balances, benefits, dependents via Composio toolkit over Rube MCP. Use after setting active connection.