Worker onboarding
This guide covers the contractor-side onboarding flow for IC and COR engagements, from the worker invitation through contract signing, identity verification, payout method setup, and onboarding tracking.
For the employer-side contract creation flow that precedes these steps, see Hiring & contracts. For ongoing management of active contracts, see Manage contracts.
All endpoints in this guide use a worker-scoped token, not the admin token used in employer flows. See Getting started for token generation.
Generate the worker session
When the contract reaches pending_signature status, 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 of building the signing UI, pass the contract_id to POST /magic-link and redirect the contractor to the returned URL.
Subscribe to contract.status.updated to detect when the contract transitions to pending_signature.
Sign the contract
The contractor signs the engagement agreement using the worker token. The contract advances to active status once signed.
Pass the contractor’s signature and signer_title in the request body.
Submit identity verification
Start an identity verification session through Veriff and redirect the contractor to the returned URL. Once the contractor 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 payout method
Bank field requirements vary by country and currency. Retrieve the supported routes and required fields before rendering the payout setup form, then create the payout method.
Call the supported routes and requirements endpoints first; use their responses to render the correct form fields before submitting the payout method.
Deel supports multiple payout method types beyond standard bank transfer (including Wise, PayPal, Coinbase, and Deel Card). For the full catalogue, see the Payouts API reference.
Configure auto-withdrawal (optional)
Auto-withdrawal disburses available balance to the contractor’s primary payout method automatically as it accrues, removing the need for the contractor to request each withdrawal manually.
If auto-withdrawal is disabled, contractors withdraw earned balance manually via POST /payouts/withdrawals. See Manage contracts for balance retrieval and manual withdrawal patterns.
Review compliance documents
Compliance document requirements vary by country and contract type. Retrieve the list to display required documents to the contractor.
IC compliance document upload and acknowledgement are not yet available via API. Use the list endpoint above to surface required documents in your UI, then redirect contractors to the Deel-hosted UI (via POST /magic-link) to complete them. EOR contracts have full upload and acknowledgement endpoints; see the EOR worker onboarding guide.
Tax form completion (W-8, W-9, and country-equivalent forms) is not available via API. Contractors must complete tax forms through the Deel-hosted UI. This applies to all Embedded integrations.
Key webhook events
See the Webhooks guide for event payload structure and signature verification.
Next steps
Ongoing operations: amendments, invoices, timesheets, time off, and termination.
Employer-side contract creation that precedes this guide.
Compare the worker-side flow for EOR employees.
Authentication, worker token generation, and environment setup.