Added new response fields: providers[].contribution_options, providers[].min_contribution, providers[].max_contribution.
Endpoint: GET /v2/eor/benefits
API Reference: Retrieve Benefits by Country
We are introducing a set of new API endpoints to enhance support for Employer of Record (EOR) worker operations, including compliance document management and bank account handling.
GET /v2/eor/workers/compliance-documents
Returns a list of required and optional compliance documents associated with an EOR employee.
Scopes: worker:read
Allowed tokens: OAUTH2:PERSONAL
GET /v2/eor/workers/compliance-documents/:document_id/templates/download
Retrieves a downloadable template for a specific compliance document, if available.
Scopes: worker:read
Allowed tokens: OAUTH2:PERSONAL
POST /v2/eor/workers/compliance-documents/:document_id
Uploads an employee compliance document.
Scopes: worker:write
Allowed tokens: OAUTH2:PERSONAL
GET /v2/eor/workers/banks/guide
Provides a structured guide (form schema) for submitting bank account details.
Scopes: worker:read
Allowed tokens: OAUTH2:PERSONAL
POST /v2/eor/workers/banks
Allows submission of bank account details for an EOR employee.
Scopes: worker:write
Allowed tokens: OAUTH2:PERSONAL
POST /v2/eor/workers/contracts/:contract_id/signatures
Enables workers to sign a contract by submitting a typed signature.
Scopes: worker:write
Allowed tokens: OAUTH2:PERSONAL
GET /v2/eor/workers/contracts/:contract_id/offer-letter
Returns a rendered HTML preview of the job offer letter for a specific EOR contract.
Scopes: worker:read
Allowed tokens: OAUTH2:PERSONAL
GET /v2/eor/workers/contracts/:contract_id/employee-agreement/download
Provides a downloadable PDF link to the employee agreement associated with the given EOR contract.
Scopes: worker:read
Allowed tokens: OAUTH2:PERSONAL
🔍 Dynamic Field Support
Bank account forms are now dynamically defined via the guide endpoint, enabling country-specific validations and input schemas.
📎 Template-Driven Document Submission
Workers can now download blank templates for required compliance documents directly via the API.
🖊️ Contract Signing
Sign employment contracts digitally with a simple string-based signature submission.
📄 Offer Letter Rendering
Allows workers to preview the HTML-formatted job offer letter for EOR contracts.
📃 Employee Agreement Download
Enables clients to preview or download the finalized employee agreement, giving full transparency and access to finalized contractual documentation.
state, work_hours_per_week and contract_duration_in_days.
state should only be sent when the GET v2/lookups/countries route returns a valid list of states.rules added to options within questions. These follow the same behavior as question rules:
rule passes, the option becomes disabled and its value must not be sent.start_date and end_date now return the correct allowed date ranges.is_disabled property added to pages, sections, questions, and options. When set to true:
is_required for questions) can be ignored.rules pass.is_disabled is true, these values are not guaranteed valid and should not be used or displayed.must_request_validation added to the Job scope question to indicate whether validation through POST v2/eor/job-scopes/validate is required.Job scope appears as Project description instead and validation is not mandatory.Currencies question now returns all supported currencies as optionsMultiple type has been renamed to Nested to better conform with design practices.currency from questions as it was redundant. Instead, use the currency as selected by the user for CURRENCY typed questions instead.Endpoint:GET /rest/v2/forms/eor/create-contract/:country_code
API Reference: Fetch EOR Contract form
We simplified the payload by removing the emailproperty from payload. We are now getting this information from the employee email provided during Create an EOR contract.
Endpoint: POST /rest/v2/eor/worker
API Reference: Create EOR Worker
Example:
curl --request POST \
--url https://api.letsdeel.com/rest/v2/eor/worker \
--header 'accept: application/json' \
--header 'authorization: Bearer {YOUR_ORG_TOKEN}' \
--data '{
"data": {
"contract_id": "mp4y66j"
}
}'
We updated this endpoint to retrieve all required fields common across all countries. The fields are:
street: Worker's address street (required)city: Worker's address city (required)state: Worker's address state/province (optional)zip_code: Worker's address zip code (required)phone: Worker's phone (required)tax_residence: Worker's tax residency country (required)is_payslip_access_allowed: Determine if worker will have access to payslip's.is_compliance_access_allowed: Determine if worker will have access to compliance.Note: We still retrieve all other fields that are country specific.
Endpoint: GET /rest/v2/forms/eor/worker-additional-fields/{country_code}
API Reference: Get worker additional fields for EOR
A new endpoint has been implemented to save the additional fields related to an Employee of Record (EOR) worker. The endpoint payload is dynamic and the payload available properties can be retrieved using Get worker additional fields for (EOR) endpoint .
Endpoint: POST /rest/v2/eor/workers/contracts/:contract_id/additional-information
API Reference: Add additional information
Example
curl --request POST \
--url \
https://api.letsdeel.com/v2/rest/v2/eor/workers/contracts/{CONTRACT_ID}/additional-information --header 'accept: application/json' \
--header 'authorization: Bearer {API_TOKEN}' \
--header 'content-type: application/json' \
--data '
{
"data": {
"tax_residence": "United States",
"phone": "+1-555-123-4567",
"street": "123 Main St",
"city": "New York",
"zip_code": "10001",
"is_payslip_access_allowed": true,
"is_compliance_access_allowed": true,
"dob": "1990-01-01",
"id_type": "Passport",
"passport_number": "AB1234"
}
}
'
Added new response fields: phone, address, created_at, sic_number, updated_at, archived_at, industry_name .
Added new query filters: cursor, sort_order, limit, include_payroll_settings, include_archived, global_payroll, legal_entity_id and type.
Endpoint: GET /v2/legal-entities
API Reference: List of legal entities
Description: Endpoint used to fetch basic information for an EOR contract, along with employment costs associated to it
Endpoint: GET /v2/eor/contracts/:contract_id/details
API Reference Retrieve EOR Contract Details
Example:
curl --request GET \
--url https://api.letsdeel.com/v2/eor/contracts/{{contract_id}}/details \
--header 'accept: application/json' \
--header 'authorization: Bearer {YOUR_ORG_TOKEN}'
Description: Extended scope_of_work input field to be passed as an object containing scope_template_id and scope_validation_id. New fields were added to response: costs, employment, compensation_details, client, employee, health_plan, job_title, seniority,created_at
Endpoint: POST /v2/eor
API Reference: Create an EOR contract
Description: Endpoint used to fetch all pre-populated job scopes from the Deel collection. Using those job scopes will automatically approve the job scope without the need for AI or human interaction.
Endpoint: GET /v2/eor/job-scopes
API Reference List of Job Scope Templates
Example:
curl --request GET \
--url https://api.letsdeel.com/v2/eor/job-scopes \
--header 'accept: application/json' \
--header 'authorization: Bearer {YOUR_ORG_TOKEN}'
You can filter templates by team by adding the optional team query parameter:
curl --request GET \
--url https://api.letsdeel.com/v2/eor/job-scopes?team={TEAM_ID} \
--header 'accept: application/json' \
--header 'authorization: Bearer {YOUR_ORG_TOKEN}'
Description: The endpoint is in charge of validating that a job scope is valid given a job title and employee name. After the job scope passes validation, the contract should be able to be processed and return the employment costs results automatically. If job scope validation passes, it goes to manual approval. If the client uses a provided job scope template using the Fetch job scope templates endpoint, there is no need to run job scope validation.
Endpoint: POST /v2/eor/job-scopes/validate
Required fields:
API Reference Request Job Scope Validation
Example:
curl --request POST \
--url https://api.letsdeel.com/v2/eor/job-scopes/validate \
--header 'accept: application/json' \
--header 'authorization: Bearer {YOUR_ORG_TOKEN}' \
--header 'content-type: application/json' \
--data '{
"data": {
"employment_country": "US",
"team_id": "123e4567-e89b-12d3-a456-426614174000",
"job_scope": "Software development and maintenance.",
"job_title": "Software Engineer",
"employee_name": "John Doe",
"client_legal_entity_id": "123e4567-e89b-12d3-a456-426614174002"
}
}'
Description: Used to gather information from the created contract together with the employment costs of the employee. This employment costs is used to display to the end-customer in order to get an accurate calculation of the amount to be paid per month;
Endpoint: GET /v2/eor/additional-costs/{country}
Parameters:
API Reference: Get EOR Additional Costs
Example:
curl --request GET \
--url https://api.letsdeel.com/v2/eor/additional-costs/US \
--header 'accept: application/json' \
--header 'authorization: Bearer {YOUR_ORG_TOKEN}'
The response includes information about allowances and non-statutory costs associated with the specified country.
Description: Retrieves detailed information about the organization's hierarchical structure, including departments and teams.
Endpoint GET /v2/hris/organization_structures
API Reference: Get Organization Structure
Example:
curl --request GET \
--url https://api.letsdeel.com/v2/hris/organization_structures \
--header 'accept: application/json' \
--header 'authorization: Bearer {YOUR_ORG_TOKEN}'
Endpoint: PUT /rest/v2/people/{id}/department
API Reference: Update organization structure
Notes:
Introduced new query parameter expand as optional
A new field has been introduced to both of these APIs to include cost centers associated with a contract in the response.
Endpoints: GET /rest/v2/contracts and GET /rest/v2/contracts/{contract_id}
API references: List of contracts and Retrieve a single contract
Details
By Default, cost_centers object is optional in contracts payload. To include it, make sure to set expand query parameter to cost_centers value.
Example [List of contracts]
curl --location 'https://api.letsdeel.com/rest/v2/contracts?expand=cost_centers' \
--header 'Authorization: Bearer {API_TOKEN}'
Example [Retrieve a single contract]
curl --location 'https://api.letsdeel.com/rest/v2/contracts/{{contract_id}}?expand=cost_centers' \
--header 'Authorization: Bearer {API_TOKEN}'
Introduced new response field is_discriminatory and updated existing is_mandatory field
A new is_discriminatory field has been introduced to response payload, which specifies if a benefit is discriminatory. Existing is_mandatory field no longer considers benefit discriminatory data.
Endpoint: GET /v2/eor/benefits
API Reference: Get list of benefits per country
New Optional Parameter: invite_employee_to_app
A new field has been introduced to allow automatic onboarding invitations for employees.
Endpoint: POST /rest/v2/contracts/gp
API reference: Create a contract
Details
When invite_employee_to_app is set to true, and if the employee app is enabled for the account, the invited employee will receive an email invitation to join the platform.
This feature streamlines the onboarding process by ensuring employees are proactively included in the Deel ecosystem.
Example
curl --request POST \
--url \
https://api.letsdeel.com/v2/rest/contracts/gp --header 'accept: application/json' \
--header 'authorization: Bearer {API_TOKEN}' \
--header 'content-type: application/json' \
--data '
{
"data": {
"client": {
"legal_entity": {
"id": "00000000-0000-0000-0000-000000000000"
},
"team": {
"id": "00000000-0000-0000-0000-000000000000"
}
},
"employee": {
"first_name": "Jane",
"last_name": "Doe",
"email": "[email protected]",
"address": {
"street": "Deel Street 500",
"city": "Denver",
"zip": "44000",
"country": "US"
},
"work_email": "[email protected]",
"nationality": "US",
"employee_number": "100"
},
"job_title": "Designer",
"employment": {
"type": "Full-time",
"start_date": "2023-01-01",
"holidays": {
"allowance": 25,
"start_date": "2023-01-01"
}
},
"compensation_details": {
"scale": "YEAR",
"salary": 50000,
"currency": "GBP"
},
"invite_employee_to_app": true
}
}
'
Endpoint: POST /rest/v2/candidates
API Reference: Create a Candidate
Notes:
/candidatesendpoint.A new endpoint has been implemented to create an Employee of Record (EOR) worker with minimal required data. This EOR worker is automatically linked to the provided contract.
Use Case: Implement this endpoint to create an EOR worker and prepare them for the onboarding process in Deel. This is typically used when you already have a contract created and the worker's email address.
Endpoint: POST /rest/v2/eor/worker
API Reference: Create EOR Worker
curl --request POST \
--url https://api.letsdeel.com/rest/v2/eor/worker \
--header 'accept: application/json' \
--header 'authorization: Bearer {YOUR_ORG_TOKEN}' \
--data '{
"data": {
"email": "[email protected]",
"contract_id": "mp4y66j"
}
}'