For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
SupportDeel Home
OverviewPlatformEmployer of RecordContractorsGlobal PayrollHREmbeddedDeel ITAPI ReferenceChangelog
OverviewPlatformEmployer of RecordContractorsGlobal PayrollHREmbeddedDeel ITAPI ReferenceChangelog
  • Resources
    • Blog
    • Community
    • API spec
  • Contractors
    • Introduction
    • Invoice adjustments
    • Timesheets
  • Common Use Cases
    • Sign contracts and amendments in bulk
    • Give bonus to contractors
    • Reimburse contractor expenses
  • Endpoints
      • PATCHAdd external Id
      • POSTCreate a new contract
      • GETList of contracts
      • GETRetrieve a single contract
LogoLogo
SupportDeel Home
EndpointsContracts

Add external Id

PATCH
/contracts/:contract_id
PATCH
/rest/v2/contracts/:contract_id
$curl -X PATCH https://api.letsdeel.com/rest/v2/contracts/37nex2x \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "data": {
>    "external_id": "5f0b87ae-58bf-4ca6-944a-ecbecf3025d6"
>  }
>}'
1{
2  "id": "123e4567-e89b-12d3-a456-426614174000",
3  "type": "ongoing_time_based",
4  "title": "Software Development Contract",
5  "client": {
6    "team": {
7      "id": "team-xyz789",
8      "name": "Engineering Team"
9    },
10    "id": "team-abc123",
11    "email": "string",
12    "full_name": "Acme Corp",
13    "legal_entity": {
14      "id": "team-xyz789",
15      "name": "Engineering Team",
16      "type": "company",
17      "email": "test@example.com",
18      "subtype": "general-partnership",
19      "vat_number": "123456789",
20      "registration_number": "123456789"
21    }
22  },
23  "status": "in_progress",
24  "worker": {
25    "id": "team-abc123",
26    "email": "client@example.com",
27    "country": "US",
28    "full_name": "Acme Corp",
29    "last_name": "Doe",
30    "first_name": "John",
31    "nationality": "US",
32    "date_of_birth": "",
33    "expected_email": "test@example.com",
34    "alternate_email": [
35      {
36        "email": "test@example.com",
37        "isVerified": true
38      }
39    ]
40  },
41  "created_at": "2022-01-01T00:00:00Z",
42  "signatures": {
43    "signed_at": "2022-01-01T00:00:00Z",
44    "client_signature": "Jane Doe",
45    "client_signed_at": "2022-01-01T00:00:00Z",
46    "worker_signature": "Jane Doe",
47    "worker_signed_at": "2022-01-01T00:00:00Z"
48  },
49  "start_date": "2022-01-01T00:00:00Z",
50  "updated_at": "2022-05-02T00:00:00Z",
51  "invitations": {
52    "client_email": "client@example.com",
53    "worker_email": "worker@example.com"
54  },
55  "is_archived": "false",
56  "special_clause": "Special clause",
57  "termination_date": "2022-01-01T00:00:00Z",
58  "quote": {
59    "benefits": [
60      {
61        "fee": 200.5,
62        "name": "Health Insurance",
63        "plan": "Premium",
64        "price": 150.75,
65        "fee_usd": 220,
66        "currency": "USD",
67        "price_usd": 170.5
68      }
69    ],
70    "currency": "USD"
71  },
72  "job_title": "Backend Developer",
73  "seniority": {
74    "id": 1,
75    "name": "Mid (Individual Contributor Level 2)",
76    "level": 2
77  },
78  "external_id": "external_id",
79  "who_reports": "client",
80  "cost_centers": [
81    {
82      "name": "6P73USR022JKJ2KU1",
83      "number": "553",
84      "allocation_percentage": 100
85    }
86  ],
87  "custom_fields": [
88    {
89      "name": "Employee ID",
90      "value": "54234"
91    }
92  ],
93  "notice_period": 30,
94  "scope_of_work": "Scope of work",
95  "work_schedule": {
96    "days": [
97      {
98        "day": "MONDAY",
99        "end": "17:00:00",
100        "start": "09:00:00",
101        "work_hours": 8
102      }
103    ],
104    "name": "34ZNYKYL3G",
105    "country": "IN",
106    "worker_types": [
107      "SALARIED_DIRECT_EMPLOYEE_PAYROLL"
108    ],
109    "work_schedule_type": "Fixed work schedule",
110    "work_hours_per_week": 40,
111    "employment_type": "FULL_TIME"
112  },
113  "employment_type": "FULL_TIME",
114  "contract_template": {
115    "id": "37nex2x",
116    "title": "UK Employment Contract 2022."
117  },
118  "work_statement_id": "123e4567-e89b-12d3-a456-426614174000",
119  "employment_details": {
120    "type": "full_time",
121    "days_per_week": 5,
122    "hours_per_day": 8,
123    "probation_period": 30,
124    "paid_vacation_days": 20
125  },
126  "compensation_details": {
127    "scale": "hourly",
128    "amount": "100",
129    "cycle_end": 31,
130    "frequency": "monthly",
131    "currency_code": "GBP",
132    "first_payment": "500",
133    "cycle_end_type": "DAY_OF_MONTH",
134    "first_payment_date": "2024-08-30T20:59:59.999+00:00",
135    "gross_annual_salary": "50000",
136    "gross_signing_bonus": "5000",
137    "gross_variable_bonus": "5000"
138  }
139}

Sets an external identifier. Link your internal reference IDs, such as employee numbers or ERP keys, to a Deel worker. The external ID must be unique and, once set, can be used as a filter when listing contracts to directly look up Deel records from an external system. Token scopes: contracts:write

Was this page helpful?
Previous

Create a new contract

Next
Built with

Authentication

AuthorizationBearer
## Authentication The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail. ```curl curl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication)
OR
AuthorizationBearer
Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

Path parameters

contract_idstringRequired
Deel contract id.

Request

Contract object that needs to be created
dataobjectRequired

Response

Successful operation.
idstring>=1 character
Unique identifier for the contract.
typeenum
Type of a contract.
titlestring>=1 character
Title of the contract.
clientobject or null
Client details associated with the contract.
statusenum
Status of a contract in Deel workflow.
workerobject or null
Worker details associated with the contract.
created_atstringformat: "date-time"
Date and time when the contract was created.
signaturesobject
Signature information for the contract parties.
start_datestringformat: "date-time"
Date and time when the contract starts.
updated_atstringformat: "date-time"
Date and time when the contract was updated.
invitationsobject
Invitation email addresses for signing the contract.
is_archivedboolean or null
Flag to indicate if the contract is archived.
special_clausestring or null
Special clause of the contract.
termination_datestring or null
Date and time when the contract ends.
quoteobject
EOR quote approved by Deel.
job_titlestring
Job title associated with the contract.
seniorityobject or null
Seniority describes level of expertise at a job e.g. junior.
external_idstring or null
External identifier of the contract.
who_reportsstring
Who reports the hours.
cost_centerslist of objects
List of cost centers associated with the contract.
custom_fieldslist of objects or null
List of custom fields attached to the contract.
notice_perioddouble or null
Notice period in days.
scope_of_workstring or null
Scope of work of the contract.
work_scheduleobject or null
Defines a work schedule including working days, hours, and employment details
employment_typeenum or null
Type of employment.
Allowed values:
contract_templateobject or null
Contract template details.
work_statement_idstring or null
The unique identifier of the associated work statement.
employment_detailsobject

Employment-related details for the contract.

compensation_detailsobject
Compensation and payment configuration for the contract.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error

Authentication

The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.

1curl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \
2  -H 'Authorization: Bearer YOUR-TOKEN-HERE'

Learn more about authentication

Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/