case_type.We've introduced two new optional fields to the request payload of the POST /rest/v2/eor endpoint to provide greater flexibility and compliance with local labor regulations:
API reference
employment.sick_leave_days (optional)employment.seniority_date (optional)Endpoint: GET /rest/v2/time-offs/policy-validation-templates
Endpoint: POST /rest/v2/time_offs
Added new optional field in requestBody: status - Status for the time off request. When set to REQUESTED the time off should be reviewed later through the Approve/Reject time off api.
We’re excited to announce several new updates and improvements across our Time Off and Timesheets APIs to make your integrations more powerful and flexible. Below is a detailed breakdown of the latest changes:
Endpoint: POST /rest/v2/time-offs
Scopes: time-off:write
Allowed Tokens:
OAUTH2:ORGANIZATIONAL, OAUTH2:PERSONAL, PAT:ORGANIZATIONAL, PAT:PERSONAL
What’s new:
policy_id, removing the need to specify a time_off_type_id.PENDING status.start_date and end_date fields now accept both YYYY-MM-DD and ISO 8601 date formats. We recommend using YYYY-MM-DD for consistency.multipart/form-data.Endpoint: PATCH /rest/v2/time-offs/:id
Scopes: time-off:write
Allowed Tokens:
OAUTH2:ORGANIZATIONAL, OAUTH2:PERSONAL, PAT:ORGANIZATIONAL, PAT:PERSONAL
What’s new:
policy_id, removing the requirement for time_off_type_id.start_date and end_date parameters in both YYYY-MM-DD and ISO string formats (we recommend YYYY-MM-DD).multipart/form-data.Endpoint: GET /rest/v2/time-offs/dailies
Scopes: time-off:read
Allowed Tokens:
OAUTH2:ORGANIZATIONAL, OAUTH2:PERSONAL, PAT:ORGANIZATIONAL, PAT:PERSONAL
What it does:
Fetch comprehensive daily information for a given date range tied to an hrisProfile:
Endpoint: POST /rest/v2/timesheets/root-presets
Scopes: timesheets:write
Allowed Tokens:
OAUTH2:ORGANIZATIONAL, OAUTH2:PERSONAL, PAT:ORGANIZATIONAL, PAT:PERSONAL
Create a new root preset for hourly reports to streamline your reporting setup.
Endpoint: GET /rest/v2/timesheets/root-presets
Scopes: timesheets:read
Allowed Tokens:
OAUTH2:ORGANIZATIONAL, OAUTH2:PERSONAL, PAT:ORGANIZATIONAL, PAT:PERSONAL
Retrieve a list of all existing hourly report root presets.
Endpoint: GET /rest/v2/timesheets/root-presets/:id
Scopes: timesheets:read
Allowed Tokens:
OAUTH2:ORGANIZATIONAL, OAUTH2:PERSONAL, PAT:ORGANIZATIONAL, PAT:PERSONAL
Fetch detailed information about a specific preset by ID.
POST /rest/v2/time-offs/validateValidate a time-off request before submission.
🔗 API Reference: Validate Time-Off
🔒 Scopes Required: time-off:read
🔑 Supported Token Types: OAUTH2:PERSONAL, OAUTH2:ORGANIZATIONAL, PAT:PERSONAL, PAT:ORGANIZATIONAL
POST /rest/v2/time-offs/reviewBatch approve or reject multiple time-off requests.
🔗 API Reference: Approve/Reject Time-Off Requests
🔒 Scopes Required: time-off:write
🔑 Supported Token Types: OAUTH2:PERSONAL, OAUTH2:ORGANIZATIONAL, PAT:PERSONAL, PAT:ORGANIZATIONAL
Check Visa Requirement EndpointGET /v2/immigration/visa-requirement/:country_code POST /v2/eor Response Schemabenefits:
cover_all – Indicates whether the benefit applies to all employees.cover_dependents – Indicates whether dependents are also covered under the benefit.These updates enhance the completeness and accuracy of the benefits object in the EOR payload.
PUT /v2/people/{id}/departmentreplace_other_positions: Indicates if this department position should replace all other positions or only append to the existing ones.GET /v2/people/{hrisProfileOid} Response Schemaprofile_organizational_structuresAdded 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