Worker onboarding
This guide covers the worker-side onboarding flow for EOR employees, from initial invitation through contract signing, compliance documents, KYC screening, bank account setup, and onboarding tracking.
All endpoints in this guide use a worker-scoped token, not the admin token used in employer flows. See Getting started for token generation.
Invite the worker
When the contract reaches waiting_for_worker_sign status, trigger the worker invitation.
Exchange your admin token and the contract_id for a short-lived worker token. Pass this token in the Authorization header for all subsequent worker-scoped requests. To use Deel’s hosted experience instead, pass the contract_id to POST /magic-link to generate a magic link.
Subscribe to contract.status.updated to detect when the contract transitions to waiting_for_worker_sign.
Review the offer letter
Before the worker signs, present the offer letter for their review.
Render this document in your UI before presenting the signature step.
Sign the employment agreement
Pass the worker’s signature in the request body. This call advances the contract status to active and moves the worker into the onboarding checklist phase.
Complete compliance documents
Compliance document requirements vary by country. Retrieve the full list first, then process each document by type.
Some documents require file upload; others require only an acknowledgement. Use the type field in the list response to determine which action to take for each document.
Submit KYC
Start an identity verification session through Veriff and redirect the worker to the returned URL. Once the worker completes the flow, read the current verification state 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 KYC step completes rather than polling.
Add a bank account
Bank field requirements vary by country and currency. Retrieve the required fields before rendering the bank setup form.
Call the guide endpoint first and use its response to render the correct form fields before submitting the bank account.
Submit additional employment information
Some countries require workers to provide supplementary data such as tax identifiers, emergency contacts, or national ID numbers. The required fields are country-specific.
Track onboarding progress
Use this endpoint to let workers view their onboarding checklist and progress; it returns the same data as the employer-side tracker.
The response includes summary.status, progress as a percentage, and checklist with step-level statuses. Subscribe to onboarding.status.updated on the employer side to track progress without polling.
Tax form completion (W-8, W-9, and country-equivalent forms) is not available via API. Workers must complete tax forms through the Deel-hosted UI. This is the primary gap in the Full Embedded onboarding experience.
Key webhook events
See the Webhooks guide for event payload structure and signature verification.
Next steps
Payslips, tax documents, time off requests, and amendment signing for active employees.
Employer-side contract creation that precedes this guide.
Employer-side onboarding tracking and time off management.
Authentication, worker token generation, and environment setup.
