> 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 worker-side onboarding flow for EOR employees in Deel's Embedded model, from contract signing through compliance and bank setup.

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.

> **Note**
>
> All endpoints in this guide use a worker-scoped token, not the admin token used in employer flows. See [Getting started](/api/embedded/getting-started) for token generation.

### Invite the worker

When the contract reaches `waiting_for_worker_sign` status, trigger the worker invitation.

<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
      </td>
    </tr>
  </tbody>
</table>

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.

<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>
        [`/eor/workers/contracts/{contract_id}/offer-letter`](/api/reference/endpoints/eor-worker-agreements/download-worker-offer-letter)
      </td>

      <td>
        Retrieve the worker's offer letter
      </td>
    </tr>
  </tbody>
</table>

Render this document in your UI before presenting the signature step.

### Sign the employment agreement

<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>
        [`/eor/workers/contracts/{contract_id}/signatures`](/api/reference/endpoints/eor-worker-agreements/sign-eor-contract-as-worker)
      </td>

      <td>
        Sign the employment agreement as the worker
      </td>
    </tr>
  </tbody>
</table>

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.

<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>
        [`/eor/workers/compliance-documents`](/api/reference/endpoints/eor-worker-compliance/get-eor-worker-compliance-documents)
      </td>

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

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

      <td>
        [`/eor/workers/compliance-documents/{document_id}`](/api/reference/endpoints/eor-worker-compliance/upload-eor-worker-compliance-document)
      </td>

      <td>
        Upload a required document
      </td>
    </tr>

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

      <td>
        [`/eor/workers/compliance-documents/{document_id}/acknowledgement`](/api/reference/endpoints/eor-worker-compliance/create-compliance-document-acknowledgement)
      </td>

      <td>
        Acknowledge a review-only document
      </td>
    </tr>
  </tbody>
</table>

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.

<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 worker to
      </td>
    </tr>

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

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

      <td>
        Retrieve the worker'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 bank account

Bank field requirements vary by country and currency. Retrieve the required fields before rendering the bank setup form.

<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>
        [`/eor/workers/banks-guide/country/{country}/currency/{currency}`](/api/reference/endpoints/eor-worker-banks/get-eor-worker-bank-guide-by-country-and-currency)
      </td>

      <td>
        Retrieve required bank fields for a country and currency
      </td>
    </tr>

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

      <td>
        [`/eor/workers/banks`](/api/reference/endpoints/eor-worker-information/create-eor-worker-bank-account)
      </td>

      <td>
        Add a bank account
      </td>
    </tr>
  </tbody>
</table>

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.

<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>
        [`/eor/workers/contracts/{contract_id}/additional-information`](/api/reference/endpoints/eor-worker-information/create-gp-worker-additional-information)
      </td>

      <td>
        Submit additional employment information
      </td>
    </tr>
  </tbody>
</table>

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

<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` on the employer side to track progress without polling.

> **Warning**
>
> 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

| Event                       | Trigger                                                  |
| --------------------------- | -------------------------------------------------------- |
| `contract.status.updated`   | Contract advanced to worker signing stage                |
| `onboarding.status.updated` | Onboarding step completed or status changed (covers KYC) |

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

## Next steps

#### [Worker self-service](/api/embedded/eor-worker-self-service)

Payslips, tax documents, time off requests, and amendment signing for active employees.

#### [Hiring & contracts](/api/embedded/eor-hiring)

Employer-side contract creation that precedes this guide.

#### [Employment management](/api/embedded/eor-management)

Employer-side onboarding tracking and time off management.

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

Authentication, worker token generation, and environment setup.