> 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://docs.deel.wtf/api/stable/llms.txt

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

This guide focuses on **Phase 2** of the hiring flow: the technical implementation of provisioning a contract. At this stage, you are translating a verbal or HRIS-based offer into a structured legal and financial object in Deel.

Creating a contract is the act of defining the "Legal Shell" of the relationship. This involves setting the pay rate, the frequency of payment, and the jurisdictional rules.

## 1. The Multi-Step Creation Strategy

While a `POST` request creates the record, a successful integration requires a three-step orchestration to ensure the contract is ready for the worker.

### Step 1: Resource mapping

You cannot create a contract with "plain text" for teams or entities. You must first resolve your internal business units to Deel UUIDs.

* **Legal Entity:** The Deel entity that "owns" the contract (e.g., your US LLC).

* *Endpoint:* [`GET /legal-entities`](/api/reference/endpoints/legal-entities/get-legal-entities)

* **Team:** The specific department or group the worker belongs to.

* *Endpoint:* [`GET /teams`](/api/reference/endpoints/organizations/get-teams)

### Step 2: The core payload

For most contractors, you will use the `ongoing_time_based` type (Fixed Rate).

**Key Payload Requirements:**

* **`type`**: Must be `ongoing_time_based` for fixed-rate recurring payroll.
* **`external_id`**: **Crucial.** Map this to your internal HRIS/ATS ID for future reconciliation.
* **`compensation_details`**: Defines the "Anchor" of the payment cycle (e.g., monthly on the 30th).

### Step 3: Handling regional requirements

The payload structure changes based on the `country_code`.

* **USA:** You **must** provide a `state_code` (e.g., `CA`, `NY`).
* **Canada:** You **must** provide a `province_code`.
* **Global:** Set `meta.documents_required: true` to automate the collection of local tax and identity forms.

## 2. Example: Fixed-Rate Implementation

This is the standard payload for an international contractor paid monthly.

```bash
curl --request POST 'https://api.letsdeel.com/rest/contracts' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "title": "Senior Backend Engineer",
    "type": "ongoing_time_based",
    "country_code": "GB",
    "start_date": "2026-02-01",
    "external_id": "EMP-9904",
    "client": {
      "legal_entity": { "id": "uuid-123" },
      "team": { "id": "uuid-456" }
    },
    "worker": {
      "first_name": "Alex",
      "last_name": "Rivera",
      "expected_email": "alex.r@example.com"
    },
    "compensation_details": {
      "amount": 8000,
      "currency_code": "GBP",
      "frequency": "monthly",
      "cycle_end": 31,
      "cycle_end_type": "DAY_OF_MONTH"
    }
  }
}'

```

## 3. Critical Configuration Logic

### The invoicing anchor

The `cycle_end` and `cycle_end_type` determine when the "Payroll Input" window closes.

* **`DAY_OF_MONTH`**: Use `31` to ensure the cycle always ends on the last day of the month, regardless of month length.
* **`payment_due_days`**: This sets your "Net" terms. Setting this to `5` means the invoice is generated on the 31st and must be funded by the 5th of the following month.

### Automation "Gotchas"

| Field            | Common Error                          | Best Practice                                                                                           |
| ---------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `expected_email` | Using a company email for a new hire. | Use their **personal email**. If they lose access to company SSO, they can still access their tax docs. |
| `start_date`     | Setting a date in the past.           | Deel allows backdating, but it will immediately generate a "Catch-up" invoice.                          |
| `job_title`      | Sending a string instead of an ID.    | Use the `job_title_id` from the reference endpoint for cleaner reporting.                               |

## 4. Next Step: Transition to Signature

Once this call returns a `201 Created`, the contract is a **Draft**. To proceed, you must now move to the **Signatures & Invitations** guide to make it legally visible to the worker.