openapi: 3.1.0
info:
title: Deel Core API
description: |
Core organizational, contract, and people APIs for Deel. Covers organizations,
legal entities, departments, groups, managers, cost centers, contracts (IC, EOR,
Global Payroll), invoice adjustments, lookups, magic links, tasks, and custom fields.
Authentication uses bearer Organization or Personal API tokens generated from the
Deel Developer Center. Production base URL is https://api.letsdeel.com/rest/v2 and
the sandbox is https://api-sandbox.demo.deel.com/rest/v2.
version: '2026-05-25'
contact:
name: Deel Developer Support
url: https://developer.deel.com/
termsOfService: https://www.deel.com/legal/terms-of-service/
license:
name: Deel Developer Terms
url: https://www.deel.com/legal/
servers:
- url: https://api.letsdeel.com/rest/v2
description: Production
- url: https://api-sandbox.demo.deel.com/rest/v2
description: Sandbox
security:
- BearerAuth: []
tags:
- name: Organizations
description: Organization profile, child organizations, structure, departments, groups
- name: Legal Entities
description: Client legal entities, industries
- name: Contracts
description: IC and EOR contract list and detail
- name: Invoice Adjustments
description: Add, update, delete, and review invoice line items
- name: Lookups
description: Countries, currencies, job titles, seniority levels, time-off types
- name: Magic Link
description: Generate single-use deep links into the Deel app
- name: Managers
description: Manager directory for the organization
- name: Custom Fields
description: Custom fields on contracts and people
paths:
/organizations:
get:
operationId: getOrganizations
summary: Retrieve Organization
description: Returns the current organization profile and child organizations the API token can access.
tags: [Organizations]
responses:
'200':
description: Organization details
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationListResponse'
'401': { $ref: '#/components/responses/Unauthorized' }
'429': { $ref: '#/components/responses/RateLimited' }
/organizations/structure:
get:
operationId: getOrganizationStructure
summary: Retrieve Organization Structure
description: Returns the organization tree of departments, groups, and reporting relationships.
tags: [Organizations]
responses:
'200':
description: Organization structure
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationStructure'
/legal-entities:
get:
operationId: getLegalEntities
summary: List Legal Entities
description: Returns the client legal entities registered under the organization.
tags: [Legal Entities]
responses:
'200':
description: Legal entity list
content:
application/json:
schema:
$ref: '#/components/schemas/LegalEntityListResponse'
post:
operationId: createLegalEntity
summary: Create A New Legal Entity
tags: [Legal Entities]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LegalEntityCreate'
responses:
'201':
description: Legal entity created
content:
application/json:
schema:
$ref: '#/components/schemas/LegalEntity'
/contracts:
get:
operationId: getContracts
summary: List Of Contracts
description: |
Returns a paginated list of contract summaries with optional filtering by status,
type, team, country, currency, external ID, or a name search term. Token scopes:
`contracts:read`.
tags: [Contracts]
parameters:
- { name: after_cursor, in: query, schema: { type: string } }
- { name: limit, in: query, schema: { type: integer, default: 20, maximum: 100 } }
- { name: order_direction, in: query, schema: { type: string, enum: [asc, desc] } }
- name: types
in: query
schema:
type: array
items: { type: string, enum: [ongoing_time_based, pay_as_you_go_time_based, milestones, eor, global_payroll, direct_employee, cor] }
- name: statuses
in: query
schema:
type: array
items: { type: string, enum: [new, in_progress, waiting_for_review, waiting_for_signature, active, terminated, cancelled, completed] }
- { name: team_id, in: query, schema: { type: string } }
- { name: external_id, in: query, schema: { type: string } }
- { name: countries, in: query, schema: { type: array, items: { type: string } } }
- { name: currencies, in: query, schema: { type: array, items: { type: string } } }
- { name: search, in: query, schema: { type: string } }
responses:
'200':
description: Contract list
content:
application/json:
schema: { $ref: '#/components/schemas/ContractListResponse' }
'401': { $ref: '#/components/responses/Unauthorized' }
'429': { $ref: '#/components/responses/RateLimited' }
/contracts/{contract_id}:
get:
operationId: getContract
summary: Retrieve A Single Contract
tags: [Contracts]
parameters:
- { name: contract_id, in: path, required: true, schema: { type: string } }
responses:
'200':
description: Contract detail
content:
application/json:
schema: { $ref: '#/components/schemas/Contract' }
/invoice-adjustments:
get:
operationId: getInvoiceAdjustments
summary: List Invoice Adjustments
description: Returns invoice line items across the organization for the current pay cycle window.
tags: [Invoice Adjustments]
parameters:
- { name: contract_id, in: query, schema: { type: string } }
- { name: status, in: query, schema: { type: string, enum: [pending, approved, declined, paid] } }
responses:
'200':
description: Invoice adjustments
content:
application/json:
schema: { $ref: '#/components/schemas/InvoiceAdjustmentList' }
post:
operationId: createInvoiceAdjustment
summary: Create An Invoice Adjustment
description: Add a bonus, deduction, commission, expense, or other line item to a contractor invoice.
tags: [Invoice Adjustments]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/InvoiceAdjustmentCreate' }
responses:
'201':
description: Invoice adjustment created
content:
application/json:
schema: { $ref: '#/components/schemas/InvoiceAdjustment' }
/lookups/countries:
get:
operationId: getCountries
summary: Retrieve Country List
description: Returns all countries with visa support, EOR availability, and sub-territories.
tags: [Lookups]
responses:
'200':
description: Country list
content:
application/json:
schema: { $ref: '#/components/schemas/CountryListResponse' }
/lookups/currencies:
get:
operationId: getCurrencies
summary: Retrieve Supported Currency List
tags: [Lookups]
responses:
'200':
description: Currency list
content:
application/json:
schema: { $ref: '#/components/schemas/CurrencyListResponse' }
/lookups/job-titles:
get:
operationId: getJobTitles
summary: Job Titles List
tags: [Lookups]
responses:
'200': { description: Job titles, content: { application/json: { schema: { $ref: '#/components/schemas/JobTitleListResponse' } } } }
/lookups/seniority-levels:
get:
operationId: getSeniorityLevels
summary: Retrieve Seniority Levels
tags: [Lookups]
responses:
'200': { description: Seniority levels, content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: '#/components/schemas/SeniorityLevel' } } } } } } }
/magic-link:
post:
operationId: createMagicLink
summary: Create Magic Link
description: Generate a single-use deep link into the Deel app for a worker or admin.
tags: [Magic Link]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [user_id, target]
properties:
user_id: { type: string }
target: { type: string, description: "Deel app target route" }
expires_in_minutes: { type: integer, default: 60 }
responses:
'200':
description: Magic link
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
url: { type: string, format: uri }
expires_at: { type: string, format: date-time }
/managers:
get:
operationId: getManagers
summary: Retrieve List Of Managers
tags: [Managers]
responses:
'200': { description: Manager list, content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: '#/components/schemas/Manager' } } } } } } }
post:
operationId: createManager
summary: Create A Manager
tags: [Managers]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ManagerCreate' }
responses:
'201': { description: Manager created, content: { application/json: { schema: { $ref: '#/components/schemas/Manager' } } } }
/custom-fields/contracts:
get:
operationId: getCustomFieldsContracts
summary: List Contract Custom Fields
tags: [Custom Fields]
responses:
'200': { description: Custom fields, content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: '#/components/schemas/CustomField' } } } } } } }
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: opaque
description: Deel Organization or Personal API token issued from the Developer Center.
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: UUID v4 idempotency key for safe retry. Responses are cached for 24 hours.
schema: { type: string, format: uuid }
responses:
Unauthorized:
description: Missing or invalid bearer token
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
RateLimited:
description: Rate limit exceeded (5 requests/second per organization)
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
schemas:
Error:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code: { type: string }
message: { type: string }
field: { type: string }
OrganizationListResponse:
type: object
properties:
data:
type: array
items: { $ref: '#/components/schemas/Organization' }
Organization:
type: object
properties:
id: { type: string }
name: { type: string }
country: { type: string }
currency: { type: string }
created_at: { type: string, format: date-time }
external_id: { type: string }
OrganizationStructure:
type: object
properties:
data:
type: object
properties:
departments: { type: array, items: { $ref: '#/components/schemas/Department' } }
groups: { type: array, items: { $ref: '#/components/schemas/Group' } }
Department:
type: object
properties:
id: { type: string }
name: { type: string }
parent_id: { type: string }
Group:
type: object
properties:
id: { type: string }
name: { type: string }
type: { type: string }
LegalEntityListResponse:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/LegalEntity' } }
LegalEntity:
type: object
properties:
id: { type: string }
name: { type: string }
country: { type: string }
registration_number: { type: string }
industry: { type: string }
currency: { type: string }
LegalEntityCreate:
type: object
required: [name, country]
properties:
name: { type: string }
country: { type: string, description: "ISO 3166-1 alpha-2" }
registration_number: { type: string }
industry: { type: string }
currency: { type: string }
ContractListResponse:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/Contract' } }
page:
type: object
properties:
limit: { type: integer }
after_cursor: { type: string }
Contract:
type: object
properties:
id: { type: string }
external_id: { type: string }
name: { type: string }
type: { type: string, enum: [ongoing_time_based, pay_as_you_go_time_based, milestones, eor, global_payroll, direct_employee, cor] }
status: { type: string, enum: [new, in_progress, waiting_for_review, waiting_for_signature, active, terminated, cancelled, completed] }
country: { type: string }
currency: { type: string }
team:
type: object
properties:
id: { type: string }
name: { type: string }
worker:
type: object
properties:
id: { type: string }
name: { type: string }
email: { type: string, format: email }
start_date: { type: string, format: date }
created_at: { type: string, format: date-time }
InvoiceAdjustmentList:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/InvoiceAdjustment' } }
InvoiceAdjustment:
type: object
properties:
id: { type: string }
contract_id: { type: string }
amount: { type: number }
currency: { type: string }
type: { type: string, enum: [bonus, commission, deduction, expense, vat, other, overtime] }
description: { type: string }
status: { type: string, enum: [pending, approved, declined, paid] }
cycle: { type: string, format: date }
created_at: { type: string, format: date-time }
InvoiceAdjustmentCreate:
type: object
required: [contract_id, amount, currency, type]
properties:
contract_id: { type: string }
amount: { type: number }
currency: { type: string }
type: { type: string, enum: [bonus, commission, deduction, expense, vat, other, overtime] }
description: { type: string }
cycle: { type: string, format: date }
CountryListResponse:
type: object
properties:
data:
type: array
items:
type: object
properties:
code: { type: string }
name: { type: string }
eor_available: { type: boolean }
visa_support: { type: boolean }
sub_territories: { type: array, items: { type: object, properties: { code: { type: string }, name: { type: string } } } }
classification: { type: string }
CurrencyListResponse:
type: object
properties:
data:
type: array
items:
type: object
properties:
code: { type: string }
name: { type: string }
symbol: { type: string }
crypto: { type: boolean }
JobTitleListResponse:
type: object
properties:
data:
type: array
items:
type: object
properties:
id: { type: string }
name: { type: string }
category: { type: string }
SeniorityLevel:
type: object
properties:
id: { type: string }
name: { type: string }
order: { type: integer }
Manager:
type: object
properties:
id: { type: string }
email: { type: string, format: email }
first_name: { type: string }
last_name: { type: string }
role: { type: string }
ManagerCreate:
type: object
required: [email, first_name, last_name]
properties:
email: { type: string, format: email }
first_name: { type: string }
last_name: { type: string }
role: { type: string, enum: [admin, manager, viewer] }
CustomField:
type: object
properties:
id: { type: string }
key: { type: string }
label: { type: string }
type: { type: string, enum: [text, number, date, select, boolean] }
required: { type: boolean }
options: { type: array, items: { type: string } }