openapi: 3.1.0
info:
title: Deel Employer of Record (EOR) API
description: |
APIs for compliantly hiring full-time employees in 100+ countries where the client
lacks a local entity. The EOR API covers the three-party signature flow, cost
calculation, country-specific benefits and hiring guides, amendments, terminations,
offboarding, and worker self-service surfaces (banks, documents, payslips, mailboxes).
version: '2026-05-25'
contact:
name: Deel Developer Support
url: https://developer.deel.com/api/employer-of-record/introduction
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: EOR Cost Calculator
description: Employment cost calculator including salary, benefits, and Deel fees
- name: EOR Hiring
description: Hiring guides, contract creation, three-party quote signing
- name: EOR Amendments
description: Amend active EOR contracts with structured approval flow
- name: EOR Terminations
description: Terminate EOR contracts with cause and offboarding workflow
- name: EOR Offboarding
description: Worker offboarding tasks and final pay
- name: EOR Benefits
description: Country-specific benefit plans and worker enrollment
- name: EOR Worker Information
description: Worker-side accounts, banks, documents, payslips, compliance
paths:
/eor/employment-cost:
post:
operationId: calculateEmploymentCost
summary: Calculate Employment Cost
description: Returns total employment cost — gross salary, employer taxes, statutory benefits, mandatory insurance, and Deel platform fee — for a target country and salary.
tags: [EOR Cost Calculator]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [country, salary]
properties:
country: { type: string, description: "ISO 3166-1 alpha-2" }
state: { type: string }
salary: { type: number }
currency: { type: string }
frequency: { type: string, enum: [yearly, monthly] }
responses:
'200':
description: Cost breakdown
content:
application/json:
schema: { $ref: '#/components/schemas/EmploymentCostBreakdown' }
/eor/hiring-guide/{country_code}:
get:
operationId: getEorHiringGuideByCountry
summary: Retrieve Detailed Hiring Guide For A Country
tags: [EOR Hiring]
parameters:
- { name: country_code, in: path, required: true, schema: { type: string } }
responses:
'200':
description: Hiring guide
content:
application/json:
schema: { $ref: '#/components/schemas/HiringGuide' }
/eor/start-date:
get:
operationId: getStartDate
summary: Fetch Start Date For EOR Contracts
description: Returns the earliest legally compliant start date for a country and worker profile.
tags: [EOR Hiring]
parameters:
- { name: country, in: query, required: true, schema: { type: string } }
responses:
'200':
description: Start date
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
earliest_start_date: { type: string, format: date }
reasoning: { type: string }
/eor/additional-costs:
get:
operationId: getAdditionalCosts
summary: Get EOR Additional Costs
tags: [EOR Hiring]
parameters:
- { name: country, in: query, required: true, schema: { type: string } }
responses:
'200':
description: Additional cost items
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/AdditionalCost' } }
/eor/contracts:
post:
operationId: createEorContract
summary: Create EOR Contract
description: |
Creates an EOR contract draft. The contract must then be quoted and signed by all
three parties (Deel, client, employee).
tags: [EOR Hiring]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/EorContractCreate' }
responses:
'201':
description: EOR contract draft created
content:
application/json:
schema: { $ref: '#/components/schemas/EorContract' }
/eor/contracts/{contract_id}/accept-quote:
post:
operationId: acceptEorQuote
summary: Accept Quote
description: Complete the client side of the three-party signature process.
tags: [EOR Hiring]
parameters:
- { name: contract_id, in: path, required: true, schema: { type: string } }
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [accepted_by]
properties:
accepted_by: { type: string }
accepted_at: { type: string, format: date-time }
responses:
'200':
description: Quote accepted
content:
application/json:
schema: { $ref: '#/components/schemas/EorContract' }
/eor/contracts/{contract_id}/cancel:
post:
operationId: cancelEorContract
summary: Cancel EOR Contract
tags: [EOR Hiring]
parameters:
- { name: contract_id, in: path, required: true, schema: { type: string } }
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason: { type: string }
effective_date: { type: string, format: date }
responses:
'200': { description: Contract cancelled }
/eor/contracts/{contract_id}/amendments:
post:
operationId: createEorAmendment
summary: Create EOR Amendment
description: Submit a contract amendment for review and three-party approval.
tags: [EOR Amendments]
parameters:
- { name: contract_id, in: path, required: true, schema: { type: string } }
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/EorAmendmentCreate' }
responses:
'201':
description: Amendment created
content:
application/json:
schema: { $ref: '#/components/schemas/EorAmendment' }
/eor/contracts/{contract_id}/terminations:
post:
operationId: createEorTermination
summary: Create EOR Termination
tags: [EOR Terminations]
parameters:
- { name: contract_id, in: path, required: true, schema: { type: string } }
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/EorTerminationCreate' }
responses:
'201':
description: Termination initiated
content:
application/json:
schema: { $ref: '#/components/schemas/EorTermination' }
/eor/benefits/{country_code}:
get:
operationId: getEorBenefitsByCountry
summary: Retrieve Benefits By Country
tags: [EOR Benefits]
parameters:
- { name: country_code, in: path, required: true, schema: { type: string } }
responses:
'200':
description: Benefit plans
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/BenefitPlan' } }
/eor/workers/{worker_id}:
get:
operationId: getEorWorker
summary: Retrieve EOR Worker Information
tags: [EOR Worker Information]
parameters:
- { name: worker_id, in: path, required: true, schema: { type: string } }
responses:
'200':
description: Worker detail
content:
application/json:
schema: { $ref: '#/components/schemas/EorWorker' }
/eor/workers/{worker_id}/payslips:
get:
operationId: getEorWorkerPayslips
summary: Retrieve EOR Worker Payslips
tags: [EOR Worker Information]
parameters:
- { name: worker_id, in: path, required: true, schema: { type: string } }
- { name: year, in: query, schema: { type: integer } }
responses:
'200':
description: Payslip list
content:
application/json:
schema:
type: object
properties:
data: { type: array, items: { $ref: '#/components/schemas/Payslip' } }
components:
securitySchemes:
BearerAuth: { type: http, scheme: bearer, bearerFormat: opaque }
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
schema: { type: string, format: uuid }
schemas:
EmploymentCostBreakdown:
type: object
properties:
data:
type: object
properties:
country: { type: string }
salary: { type: number }
currency: { type: string }
employer_costs:
type: object
properties:
gross_salary: { type: number }
employer_taxes: { type: number }
statutory_benefits: { type: number }
insurance: { type: number }
deel_platform_fee: { type: number }
total_monthly: { type: number }
total_annual: { type: number }
notes: { type: array, items: { type: string } }
HiringGuide:
type: object
properties:
data:
type: object
properties:
country: { type: string }
minimum_wage: { type: number }
notice_period_days: { type: integer }
probation_period_days: { type: integer }
working_hours_per_week: { type: integer }
mandatory_benefits: { type: array, items: { type: string } }
optional_benefits: { type: array, items: { type: string } }
public_holidays_per_year: { type: integer }
paid_time_off_days: { type: integer }
sick_leave_days: { type: integer }
maternity_leave_weeks: { type: integer }
paternity_leave_weeks: { type: integer }
termination_grounds: { type: array, items: { type: string } }
AdditionalCost:
type: object
properties:
name: { type: string }
amount: { type: number }
currency: { type: string }
frequency: { type: string, enum: [one_time, monthly, annual] }
description: { type: string }
EorContractCreate:
type: object
required: [employee, country, salary, currency, start_date]
properties:
employee:
type: object
required: [first_name, last_name, email]
properties:
first_name: { type: string }
last_name: { type: string }
email: { type: string, format: email }
nationality: { type: string }
date_of_birth: { type: string, format: date }
country: { type: string }
state: { type: string }
job_title: { type: string }
seniority_level_id: { type: string }
salary: { type: number }
currency: { type: string }
salary_frequency: { type: string, enum: [yearly, monthly] }
start_date: { type: string, format: date }
end_date: { type: string, format: date }
scope_of_work: { type: string }
external_id: { type: string }
EorContract:
type: object
properties:
id: { type: string }
status: { type: string, enum: [draft, quoted, in_progress, active, cancelled, terminated, completed] }
country: { type: string }
salary: { type: number }
currency: { type: string }
start_date: { type: string, format: date }
employee: { $ref: '#/components/schemas/EorWorker' }
signatures:
type: object
properties:
client: { type: object, properties: { signed: { type: boolean }, signed_at: { type: string, format: date-time } } }
employee: { type: object, properties: { signed: { type: boolean }, signed_at: { type: string, format: date-time } } }
deel: { type: object, properties: { signed: { type: boolean }, signed_at: { type: string, format: date-time } } }
EorAmendmentCreate:
type: object
required: [type, effective_date]
properties:
type: { type: string, enum: [salary_change, role_change, working_hours_change, benefits_change, address_change] }
effective_date: { type: string, format: date }
new_salary: { type: number }
new_currency: { type: string }
new_job_title: { type: string }
notes: { type: string }
EorAmendment:
type: object
properties:
id: { type: string }
contract_id: { type: string }
type: { type: string }
status: { type: string, enum: [pending, approved, declined, applied] }
effective_date: { type: string, format: date }
created_at: { type: string, format: date-time }
EorTerminationCreate:
type: object
required: [reason, last_working_day]
properties:
reason: { type: string, enum: [resignation, end_of_contract, mutual_agreement, performance, redundancy, gross_misconduct, other] }
last_working_day: { type: string, format: date }
notice_already_given: { type: boolean }
notes: { type: string }
EorTermination:
type: object
properties:
id: { type: string }
contract_id: { type: string }
status: { type: string, enum: [pending, in_progress, completed] }
reason: { type: string }
last_working_day: { type: string, format: date }
BenefitPlan:
type: object
properties:
id: { type: string }
name: { type: string }
provider: { type: string }
category: { type: string, enum: [health, dental, vision, retirement, life, disability, wellness, other] }
cost: { type: number }
currency: { type: string }
coverage: { type: string }
eligibility: { type: string }
EorWorker:
type: object
properties:
id: { type: string }
first_name: { type: string }
last_name: { type: string }
email: { type: string, format: email }
country: { type: string }
nationality: { type: string }
date_of_birth: { type: string, format: date }
job_title: { type: string }
start_date: { type: string, format: date }
external_id: { type: string }
Payslip:
type: object
properties:
id: { type: string }
period_start: { type: string, format: date }
period_end: { type: string, format: date }
gross: { type: number }
net: { type: number }
currency: { type: string }
download_url: { type: string, format: uri }