Create and onboard contractors
Creating a contractor engagement involves two sequential phases: you create and sign the contract, then the worker signs and completes KYC. This guide walks through both phases in order.
For an overview of IC contract types and the Embedded model, see IC embedded overview. For ongoing management of active contracts, see Manage contracts.
Prerequisites
- Employer steps: Admin-scoped API token. See Getting started for authentication setup.
- Worker steps: Worker token or magic link generation capability. See Getting started for how to generate each type.
Employer phase
Populate form data
Before rendering the contract creation form, fetch the lookup data needed for dropdowns and selectors.
Create the contract
Submit the contract creation request with the worker details, group assignment, and payment terms.
The contract_type field determines the billing model: fixed, pay_as_you_go, milestones, or tasks. Required fields: worker details (first_name, last_name, email, country), client.team (group ID), job_title, start_date, currency, and payment terms appropriate to the contract type.
The response includes the contract id and initial status. Store the id; it is required for all subsequent operations.
Attach documents (optional)
Attach a Statement of Work, NDA, or other exhibit to the contract before signing.
POST /contracts/{contract_id}/documents
Send as multipart/form-data. Multiple documents can be attached to a single contract.
Set custom fields (optional)
Attach platform-specific metadata to the contract: internal project codes, cost centre IDs, or other identifiers.
Sign the contract
Sign the contract on behalf of the end customer. The contract advances to the worker signing stage.
POST /contracts/{contract_id}/signatures
Required fields: signature, signer_title.
Send the worker invitation
Dispatch the worker signing invitation.
POST /contracts/{contract_id}/invitations
This sends the worker a Deel-branded email with a hosted signing URL. To handle the signing experience in your own platform, use this step to trigger worker token generation instead.
Worker phase
Generate a worker token via POST /workers/session and call these endpoints directly, or use POST /magic-link to redirect the worker to Deel’s hosted experience.
Worker authenticates
Generate a worker-scoped token to enable direct API calls on the worker’s behalf.
- Call
POST /workers/sessionwithcontract_idto receive a workertoken. - Call
POST /magic-linkwithcontract_idto receive a short-lived hosted UI link, valid for 5 minutes.
Worker signs the contract
The worker signs the employment agreement using the worker token. The contract advances to active status.
Worker completes KYC
Start an identity verification session through Veriff and redirect the worker to the returned URL. Once the worker finishes, read the resulting kyc_status via the KYC details endpoint.
The kyc_status field returns one of APPROVED, REJECTED, EXPIRED, EXPIRING_SOON, PENDING_REVIEW, NOT_REQUESTED, or NOT_SUBMITTED. Subscribe to onboarding.status.updated to know when the step completes rather than polling.
Tax form completion (W-8, W-9, and equivalents) is not available via API. Workers must complete tax forms through the Deel-hosted UI. This applies to all Embedded integrations.
Webhook events
See the Webhooks guide for event payload structure and signature verification.
Next steps
Amendments, invoices, timesheets, off-cycle payments, and termination for active contracts.
Overview of EOR workflows for partners offering both contract types.
Authentication, environments, token generation, and webhook setup.
Configure webhooks to receive real-time updates on contract events.
