deel-api

Deel API Integration Skill

Use this guide when building an app that integrates with the Deel REST API, in any tech stack.

Quick Reference

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)

Token Details

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:

• Organization tokens — tied to the org, survive employee departures
• Personal tokens — tied to an individual user, expire when they leave

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.

Endpoint Summary (20 total verified)

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

Top Gotchas

1. Decode the JWT first — scope tells you which endpoints return 200 vs 403
2. Sandbox vs Production use different base URLs — sandbox tokens must hit api-sandbox.demo.deel.com, not api.letsdeel.com. A sandbox token against production returns 401
3. hide_employment_data changes response shape — fields like job_title, department move into employments[0]
4. Pagination is cursor-based — use after_cursor from page.cursor, not page numbers
5. Time-off uses hris_organization_user_id — not the person UUID or worker_id
6. /time_offs list does NOT support limit — passing it returns 400
7. Contract :id is a short alphanumeric string (e.g. 5dkw6zv), not a UUID
8. Emails are an array — use person.emails.find(e => e.type === 'work')?.value
9. Route order matters (Express) — put /custom-fields before /:id
10. Deel mixes underscores and hyphens — /time_offs vs /lookups/time-off-types

Additional resources

• For complete endpoint details, response payloads, enum values, implementation patterns, and stack-specific quick starts, see reference.md

---

Last updated: 2026-03-02 by Franklin Lee