From candidate to contract

Overview

When a candidate accepts an offer in Deel’s ATS, the hiring record is complete but no contract exists yet. This guide walks through the steps to retrieve the accepted offer from the ATS, determine the correct contract type based on the offer’s worker_type, and initiate the contract creation request using Deel’s contracts API.

The process is partly manual today: offer retrieval and contract creation are separate API surfaces, and the link between them requires passing key fields from the offer (such as candidate email, employment type, and location) into the contract request.

When to use this workflow

Use this workflow when you need to:

• Automatically trigger contract creation as soon as a candidate accepts an offer
• Sync hire decisions from Deel’s ATS into a downstream HRIS or payroll system
• Build an end-to-end recruitment-to-onboarding automation without manual handoffs
• Audit which ATS applications have progressed to active contracts

Prerequisites

Before starting, ensure you have:

• A valid API token with ats:read scope to retrieve offer data
• Contract creation permissions: contracts:write scope and a Deel account configured for the relevant contract type
• A completed ATS application that has reached a COMPLETED stage with an accepted offer. See Manage candidates and applications.
• The application_id of the hired candidate

Step-by-step workflow

The following example follows Jane Doe, whose application app_01hxyzghijkl has progressed to a COMPLETED stage with an accepted offer.

$
curl --request GET 'https://api.letsdeel.com/rest/v2/ats/applications/app_01hxyzghijkl' \
>
  --header 'Authorization: Bearer YOUR-TOKEN-HERE'

1
{
2
  "data": {
3
    "id": "app_01hxyzghijkl",
4
    "candidate": {
5
      "email": "jane.doe@example.com"
6
    },
7
    "current_application_interview_plan_stage": {
8
      "interview_plan_stage": {
9
        "category_type_slug": "COMPLETED"
10
      }
11
    },
12
    "offers": [
13
      {
14
        "id": "offer_01hxyzabcdef",
15
        "offer_status": "ACCEPTED",
16
        "worker_type": "EOR_EMPLOYEE",
17
        "created_at": "2026-05-04T11:00:00Z"
18
      }
19
    ]
20
  }
21
}

$
curl --request GET 'https://api.letsdeel.com/rest/v2/ats/offers/offer_01hxyzabcdef' \
>
  --header 'Authorization: Bearer YOUR-TOKEN-HERE'

1
{
2
  "data": {
3
    "id": "offer_01hxyzabcdef",
4
    "worker_type": "EOR_EMPLOYEE",
5
    "offer_status": "ACCEPTED",
6
    "salary": { "amount": 95000, "currency": "USD", "period": "YEAR" },
7
    "start_date": "2026-06-01",
8
    "country_code": "ES",
9
    "job_title": "Senior Software Engineer"
10
  }
11
}

$
curl --request POST 'https://api.letsdeel.com/rest/v2/contracts/eor' \
>
  --header 'Authorization: Bearer YOUR-TOKEN-HERE' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
    "data": {
>
      "worker_email": "jane.doe@example.com",
>
      "job_title": "Senior Software Engineer",
>
      "country_code": "ES",
>
      "start_date": "2026-06-01",
>
      "salary": {
>
        "amount": 95000,
>
        "currency": "USD",
>
        "period": "YEAR"
>
      }
>
    }
>
  }'

$
curl --request GET 'https://api.letsdeel.com/rest/v2/contracts/{contract_id}' \
>
  --header 'Authorization: Bearer YOUR-TOKEN-HERE'

Common scenarios

Contractor instead of EOR employee

If worker_type is CONTRACTOR, use POST /contracts/ic instead. The key difference is that IC contracts require the worker to register as a contractor entity. Ensure the worker has completed their Deel contractor profile before creating the contract.

Offer not yet accepted

If offer_status is SENT (not yet ACCEPTED), the candidate has not yet accepted. Poll GET /ats/offers/{offer_id} or set up an ats.application.transitioned webhook to receive a notification when the application stage changes to COMPLETED. Do not create a contract for an unaccepted offer.

Multiple offers on one application

An application can have more than one offer (for example, if a first offer was rejected and a new one was extended). Always check the full offers array and use the offer with offer_status: "ACCEPTED". If multiple offers exist, use the one with the most recent created_at timestamp.

Troubleshooting

Next steps