> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# Worker onboarding

> Guide to the contractor-side onboarding flow for IC and COR contracts in Deel's Embedded model, from contract signing through identity verification and payout setup, plus tax form submission for US engagements.

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. Contracts under a US client legal entity also require a tax form submission before signing.

For the employer-side contract creation flow that precedes these steps, see [Hiring & contracts](/api/embedded/ic-create-onboard). For ongoing management of active contracts, see [Manage contracts](/api/embedded/ic-manage).

> **Note**
>
> This guide uses a worker-scoped token throughout, since each step represents an action the contractor takes on their own behalf. See [Getting started](/api/embedded/getting-started) for how to generate one.

### 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.

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>
        Method
      </th>

      <th>
        Endpoint
      </th>

      <th>
        Purpose
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `POST`
      </td>

      <td>
        [`/workers/session`](/api/reference/endpoints/worker-session/create-worker-access-token-v-2026-01-01)
      </td>

      <td>
        Generate a worker token for the contract
      </td>
    </tr>

    <tr>
      <td>
        `POST`
      </td>

      <td>
        [`/magic-link`](/api/reference/endpoints/magic-link/create-magic-link)
      </td>

      <td>
        Generate a short-lived hosted UI link, valid for 5 minutes
      </td>
    </tr>
  </tbody>
</table>

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`.

### Submit a tax form (US legal entities only)

This step is required only for contracts under a US client legal entity; skip to [Sign the contract](#sign-the-contract) for any other legal entity. The contractor must have a US tax form on file; submission only requires a non-terminated contract, not a signed one. Submit the form as soon as the worker record has been created.

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>
        Method
      </th>

      <th>
        Endpoint
      </th>

      <th>
        Purpose
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `POST`
      </td>

      <td>
        [`/workers/tax-forms`](/api/reference/endpoints/workers/create-a-tax-form-for-a-worker-v-2026-01-01-v-2026-07-14)
      </td>

      <td>
        Submit the contractor's US tax form for a client legal entity
      </td>
    </tr>
  </tbody>
</table>

Set `form_type` based on the contractor's US tax status:

* `W9_INDIVIDUAL`: US persons
* `W9_COMPANY`: US entities
* `W8_BEN`: non-US individuals
* `W8_BEN_E`: non-US entities

Each form type requires a different set of fields; see the endpoint reference for the full schema per type.

Pass the same `client_legal_entity_id` used when the contract was created (`client.legal_entity.id` in [Create the contract](/api/embedded/ic-create-onboard#create-the-contract)).

> **Note**
>
> Only one tax form can exist per contractor/legal-entity pair. A duplicate will return a `409`. There is no update endpoint, so validate the form data before submitting.

### Sign the contract

The contractor signs the engagement agreement using the worker token. The contract advances to `active` status once signed.

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>
        Method
      </th>

      <th>
        Endpoint
      </th>

      <th>
        Purpose
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `POST`
      </td>

      <td>
        [`/contracts/{contract_id}/signatures`](/api/embedded/ic-endpoints/contractor-hiring/create-contract-signature)
      </td>

      <td>
        Sign the contract as the worker
      </td>
    </tr>
  </tbody>
</table>

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.

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>
        Method
      </th>

      <th>
        Endpoint
      </th>

      <th>
        Purpose
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `POST`
      </td>

      <td>
        [`/veriff/session`](/api/reference/endpoints/screenings/create-veriff-session)
      </td>

      <td>
        Create a Veriff session; returns the URL to redirect the contractor to
      </td>
    </tr>

    <tr>
      <td>
        `GET`
      </td>

      <td>
        [`/screenings/kyc/details`](/api/reference/endpoints/screenings/get-kyc-details)
      </td>

      <td>
        Retrieve the contractor's current 

        `kyc_status`
      </td>
    </tr>
  </tbody>
</table>

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.

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>
        Method
      </th>

      <th>
        Endpoint
      </th>

      <th>
        Purpose
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `GET`
      </td>

      <td>
        [`/payouts/contractors/methods/bank_transfers/supported_routes`](/api/reference/endpoints/payouts/get-bank-transfer-supported-routes)
      </td>

      <td>
        List the bank transfer routes available to the contractor
      </td>
    </tr>

    <tr>
      <td>
        `GET`
      </td>

      <td>
        [`/payouts/contractors/methods/bank_transfers/requirements`](/api/reference/endpoints/payouts/get-bank-transfer-requirements)
      </td>

      <td>
        Retrieve required fields for a selected route
      </td>
    </tr>

    <tr>
      <td>
        `POST`
      </td>

      <td>
        [`/payouts/contractors/methods`](/api/reference/endpoints/payouts/create-a-bank-transfer-method-v-2026-01-01)
      </td>

      <td>
        Create a payout method using the values returned above
      </td>
    </tr>

    <tr>
      <td>
        `GET`
      </td>

      <td>
        [`/payouts/contractors/methods`](/api/reference/endpoints/payouts/fetch-all-payout-methods-v-2026-01-01)
      </td>

      <td>
        List the contractor's existing payout methods
      </td>
    </tr>

    <tr>
      <td>
        `PUT`
      </td>

      <td>
        [`/payouts/contractors/methods/{id}`](/api/reference/endpoints/payouts/update-bank-transfer-method)
      </td>

      <td>
        Update a payout method
      </td>
    </tr>
  </tbody>
</table>

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](/api/reference/endpoints/payouts).

### 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.

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>
        Method
      </th>

      <th>
        Endpoint
      </th>

      <th>
        Purpose
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `GET`
      </td>

      <td>
        [`/payouts/auto-withdrawal-setting`](/api/reference/endpoints/payouts/get-the-auto-withdrawal-setting)
      </td>

      <td>
        Retrieve the contractor's current auto-withdrawal setting
      </td>
    </tr>

    <tr>
      <td>
        `PATCH`
      </td>

      <td>
        [`/payouts/auto-withdrawal-setting`](/api/reference/endpoints/payouts/change-the-auto-withdrawal-setting-v-2026-01-01)
      </td>

      <td>
        Enable, disable, or change the auto-withdrawal setting
      </td>
    </tr>
  </tbody>
</table>

If auto-withdrawal is disabled, contractors withdraw earned balance manually via `POST /payouts/withdrawals`. See [Manage contracts](/api/embedded/ic-manage#invoices-and-payments) 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.

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>
        Method
      </th>

      <th>
        Endpoint
      </th>

      <th>
        Purpose
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `GET`
      </td>

      <td>
        [`/workers/compliance-documents`](/api/reference/endpoints/workers/list-of-worker-compliance-documents-v-2026-01-01)
      </td>

      <td>
        List compliance documents and their status
      </td>
    </tr>
  </tbody>
</table>

> **Warning**
>
> 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](/api/embedded/eor-worker-onboarding#complete-compliance-documents).

### Track onboarding progress

Retrieve the onboarding checklist and progress to let contractors see their remaining steps.

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>
        Method
      </th>

      <th>
        Endpoint
      </th>

      <th>
        Purpose
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `GET`
      </td>

      <td>
        [`/onboarding/tracker/hris_profile/{hris_profile_id}`](/api/reference/endpoints/onboarding/get-onboarding-details-by-employee-hris-profile-id-v-2026-01-01)
      </td>

      <td>
        Retrieve onboarding progress and checklist
      </td>
    </tr>
  </tbody>
</table>

The response includes `summary.status`, `progress` as a percentage, and `checklist` with step-level statuses. Subscribe to `onboarding.status.updated` to track progress without polling.

> **Warning**
>
> US tax forms (W-9 and W-8BEN variants) can be submitted via the API, as shown in [Submit a tax form](#submit-a-tax-form) above. Country-equivalent tax forms outside the US are not currently available via API; contractors must complete those through the Deel-hosted UI.

## Key webhook events

| Event                       | Trigger                                                                   |
| --------------------------- | ------------------------------------------------------------------------- |
| `contract.status.updated`   | Contract advanced through signing stages                                  |
| `onboarding.status.updated` | Onboarding step completed or status changed (covers KYC and payout setup) |
| `payment.completed`         | Withdrawal disbursed to the contractor's payout method                    |

See the [Webhooks guide](/api/webhooks/introduction) for event payload structure and signature verification.

## Next steps

#### [Manage contracts](/api/embedded/ic-manage)

Ongoing operations: amendments, invoices, timesheets, time off, and termination.

#### [Hiring & contracts](/api/embedded/ic-create-onboard)

Employer-side contract creation that precedes this guide.

#### [EOR worker onboarding](/api/embedded/eor-worker-onboarding)

Compare the worker-side flow for EOR employees.

#### [Getting started](/api/embedded/getting-started)

Authentication, worker token generation, and environment setup.