Overview

Getting started

This page covers the common setup required before working with any Embedded API guide. Complete these steps once before building employer or worker flows.

Prerequisites

Your Deel account must have the Embedded model activated before any Embedded API flows are available. Contact your Deel implementation engineer to confirm your account is configured.

All employer-side endpoints require an organization-level API token. See Get your API credentials for instructions on generating a token. Store it as an environment variable; never hardcode tokens in application code.

Authentication

Admin token (employer-side)

All employer-facing endpoints authenticate with an organization-level API token passed as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

See Authentication for token scopes and generation instructions.

OAuth (optional)

If your platform uses OAuth to act on behalf of your clients rather than a single shared admin token, refer to the OAuth guide for the authorization code flow.

Worker tokens (Full Embedded)

Worker-side endpoints use a separate worker-scoped token. In the Full Embedded model, your platform generates this server-side and passes it to the worker’s session:

Call POST /workers/session with your admin token and a contract_id to receive a short-lived worker token.

Use the returned token in the Authorization header for all worker-scoped requests. Worker tokens are scoped to a single contract and expire after a short period.

To use Deel’s hosted worker experience, redirect workers to a magic link rather than calling worker APIs directly:

Call POST /magic-link to generate a short-lived link (valid for 5 minutes) that takes the worker into the Deel onboarding UI.

With magic links, you do not call worker-scoped endpoints directly. The worker token flow applies when you are handling worker flows within your own platform.

Environments

EnvironmentBase URL
Productionhttps://api.letsdeel.com/rest/v2
Demo (sandbox)https://api-sandbox.letsdeel.com/rest/v2

All contract and amendment operations are legally binding in production. Test every flow in the sandbox environment before connecting to production data.

Webhooks

Webhooks are the recommended way to track state changes. All Embedded guides reference specific events; subscribing to these eliminates polling and makes your integration more reliable.

To configure webhooks, see the Webhooks guide. Key setup steps:

  1. Register a webhook endpoint URL in your Deel account settings.
  2. Store the signing secret and verify the X-Deel-Signature header on every incoming event.
  3. Respond with 200 OK within 10 seconds; Deel retries failed deliveries.

Multi-tenant structure

In the Embedded model, each of your end customers is represented as a group in Deel. Create one group per customer company during their onboarding via POST /groups. The id returned maps to the client.team field in all EOR and IC contract requests for that customer.

Use external_metadata to store your platform’s internal identifiers on each group, so you can reconcile records across systems without a separate mapping table.

Next steps

Hiring & contracts

Group setup, cost estimation, EOR contract creation, and employer signing.

Create and onboard contractors

IC contract creation, document attachment, and worker invitation.

Worker onboarding

Worker-side contract signing, compliance documents, KYC, and bank setup.

Manage contracts

Amendments, invoices, timesheets, and termination for active IC contracts.