Creating contracts | Deel

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
Team: The specific department or group the worker belongs to.
Endpoint: 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.

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.