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

This guide outlines the end-to-end programmatic hiring flow. It moves beyond simple API references to explain how your system should orchestrate the transition from a "New Hire" in your internal database to an "Active Contractor" ready for payroll.

The hiring lifecycle is a multi-step process involving your backend, the Deel API, and the human contractor. Understanding the state transitions is key to a successful integration.

## Phase 1: Preparation (Resource Mapping)

Before creating a contract, you must map your internal organization data to Deel’s system IDs.

* **Organization Context:** Retrieve your `team_id` and `legal_entity_id`.
* **Job Metadata:** Fetch `job_title_id` and `seniority_id`.
* **Worker Info:** Ensure you have the contractor's legal name and a unique personal email address.

## Phase 2: Contract Provisioning (The "Draft" State)

In this phase, you define the commercial terms. The contract is created but is not yet legally binding.

### 1. Create the contract object

Submit a [`POST /contracts`](/api/endpoints/contracts/create-ic-contract) request. This creates the "Legal Shell."

* **Action:** Set the `type` (e.g., `ongoing_time_based` for fixed-rate).
* **Result:** You receive a `contract_id`. The status is now `draft`.

### 2. Apply client signature

A contract cannot be sent to a worker until the Employer (you) has signed it.

* **Endpoint:** [`POST /contracts/{contract_id}/signatures`](/api/endpoints/contractor-hiring/create-contract-signature)
* **Mechanism:** Most integrations use a "Standard Template" so the signature can be applied programmatically via the API.

## Phase 3: The Invitation (The "Onboarding" State)

Now that the contract is signed by the employer, you must invite the worker to the Deel platform to complete their side of the deal.

### 1. Trigger the Invite

* **Endpoint:** [`POST /contracts/{contract_id}/invitations`](/api/endpoints/contractor-hiring/create-contract-invitation)
* **Action:** This sends the official Deel onboarding email to the worker.

### 2. Worker Action (Outside the API)

The worker receives the email and must:

1. Create or log in to their **Deel Account**.
2. Complete **Identity Verification (KYC)**.
3. Review and **Sign the Contract**.

---

## Phase 4: Activation (The "Live" State)

The contract only becomes "Active" once the worker has completed all onboarding requirements.

* **Monitoring Status:** Use a Webhook listener for `contract.status.updated`.
* **The Goal:** When the status changes to `active`, the worker is now eligible for payment inputs (bonuses, timesheets, etc.).

## The Complete Table

| Step  | Action          | API Endpoint                                                                       | Status                      | Result                   |
| ----- | --------------- | ---------------------------------------------------------------------------------- | --------------------------- | ------------------------ |
| **1** | Create Contract | [`POST /contracts`](/api/endpoints/contracts/create-ic-contract)                   | `draft`                     | Terms are saved in Deel. |
| **2** | Sign (Employer) | [`POST /signatures`](/api/endpoints/contractor-hiring/create-contract-signature)   | `awaiting_worker_signature` | Ready for the worker.    |
| **3** | Send Invite     | [`POST /invitations`](/api/endpoints/contractor-hiring/create-contract-invitation) | `invited`                   | Email sent to worker.    |
| **4** | Worker Signs    | *(User Action)*                                                                    | `active`                    | **Contract is live.**    |

## Implementation Best Practices

* **Webhook Resilience:** Do not rely solely on the API response for the "Active" state. The worker might take days to sign. Build a listener for the `contract.status.updated` event to update your internal database.
* **External ID Mapping:** Always pass your internal Employee/Candidate ID into the `external_id` field during Step 1. This is the only way to reconcile your data once the contract is active.
* **Proration Awareness:** If the worker signs halfway through a month, Deel will automatically handle the proration based on the `active` date.