Hiring & contracts
Hiring & contracts
This guide covers EOR contract creation from initial company setup through employer signing. These phases are sequential: create the group before creating any contract for that client.
All endpoints require an admin-scoped API token. See Getting started for authentication and environment setup. For managing active employment after a contract is signed, see Employment management.
Create a group
Each client company is represented as a group in Deel. Create one group per client during their onboarding.
The response includes the group id. Store it; it maps to client.team in all EOR contract requests for this client. Use the external_metadata object to store your platform’s internal identifiers on the group record, so you can reconcile records across systems without a separate mapping table.
For clients with multiple subsidiaries that share the same structural configuration, use the clone endpoint rather than repeating setup manually.
Estimate employment costs
Surface a full cost breakdown before the employer confirms the hire. Showing the total cost upfront reduces the risk of abandonment at the contract submission step.
Surface both the base cost and additional costs as a combined total before proceeding to contract creation.
Fetch the contract form
Every country has different required fields, validation constraints, and data dependencies. Retrieve the field specification for the target country at the start of each contract creation flow.
Pass start_date and work_hours_per_week as query parameters. The response pages array contains sections and questions. Each question includes the field name, type, validation constraints, and, where applicable, a data_source URL for dropdown values.
Field requirements and validation rules change as local regulations are updated. Do not cache form schemas across countries or sessions.
Retrieve reference data
Before rendering the contract form, populate dropdown fields with reference data from the lookup endpoints.
Retrieve these in parallel to minimize form load time. The benefits endpoint distinguishes statutory (mandatory, employer-paid) from optional benefits; use this to control what you surface in the form.
Validate the job scope
If using a custom job description, validate it before contract creation. An unvalidated custom scope triggers a 24-hour Deel review after submission, blocking the contract from progressing.
If validation succeeds, pass the returned validation id in employment.scope_of_work when creating the contract. To avoid validation delay entirely, use a pre-approved template from GET /eor/job-scopes and pass the scope_template_id instead.
Create the EOR contract
Submit the contract with the data collected from the previous steps.
The request body requires four nested objects: employee, employment, client (containing team set to the group id from step 1), and compensation_details. Store the returned id immediately; it is required for all subsequent operations on this contract.
The initial contract status is under_review. It transitions to waiting_for_client_sign after Deel completes its review.
Handle compliance agreements
Some countries require side agreements to be fetched and signed before the main framework agreement. This step applies to Belgium, Germany, Spain, Italy, and Tunisia.
Retrieve the document list first and filter for documents with status pending_signature. Sign each before proceeding to the framework agreement.
This step is only required for the countries listed above. For all other countries, proceed directly to framework agreement signing.
Fetching and signing side agreements requires a personal access token. Organization tokens are not supported for these endpoints.
Sign the framework agreement
Once the contract reaches waiting_for_client_sign status, sign the framework agreement to complete the employer signing phase.
After signing, the contract moves to the worker signing phase. The worker receives their invitation and completes onboarding. See Worker onboarding.
Key webhook events
See the Webhooks guide for event payload structure and signature verification.
Next steps
Track onboarding progress, manage employee data, and handle time off for active employees.
Worker-side contract signing, compliance documents, and bank setup.
Amend active contracts and process terminations.
Authentication, environments, and webhook setup.
