API versioning

Overview

The Deel API uses versioning to evolve endpoints while maintaining backward compatibility for existing integrations.

URL versioning (legacy)

The Deel API supports URL path versioning. All endpoints include a version prefix in the URL:

https://api.letsdeel.com/rest/v2/people

The /v2/ prefix identifies the major API version. This pattern remains fully supported across all API reference documentation and existing integrations.

Header versioning

The Deel API uses header-based date versioning as the standard for managing API changes. Instead of changing the URL path, you specify a version date using the X-Version request header:

X-Version: 2026-01-01

URL path versioning (/v2/) continues to work alongside header versioning. You do not need to change existing integrations. New versioned changes to API endpoints are introduced through header versions, and the /v2/ URL prefix remains in use.

Key concepts

• Deel uses date-based versioning via the X-Version header (YYYY-MM-DD format)
• Every endpoint version follows a lifecycle with three states: Beta, Stable, and Deprecated
• Omitting the X-Version header routes your request to a stable version automatically
• Beta endpoints require an explicit X-Beta: true header
• Response headers communicate the lifecycle state of the version you called

Version lifecycle timing

A new major version is expected approximately once per year. When a new version is released, the previous version enters deprecation with exactly one year of continued support before sunset.

Specifying a version

Use the X-Version request header to pin your integration to a specific API version.

1
import requests
2
import os
3
4
headers = {
5
    "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
6
    "X-Version": "2026-01-01"
7
}
8
9
response = requests.get(
10
    "https://api.letsdeel.com/rest/v2/contracts",
11
    headers=headers
12
)

Default behavior (no header)

When X-Version is omitted, the API routes your request to a stable version automatically. Existing integrations continue to work with no changes required.

If you are building a new integration, Deel recommends explicitly setting X-Version to protect against future changes.

Lifecycle states

Every endpoint version moves through a defined lifecycle. The X-State response header communicates the current state of the version you called.

Response headers

The API includes versioning-related headers in every response to communicate the current state of the endpoint you called.

1
import requests
2
import os
3
4
headers = {
5
    "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
6
    "X-Version": "2026-01-01"
7
}
8
9
response = requests.get(
10
    "https://api.letsdeel.com/rest/v2/contracts",
11
    headers=headers
12
)
13
14
state = response.headers.get("X-State")
15
is_deprecated = response.headers.get("Deprecation") == "true"
16
sunset_date = response.headers.get("Sunset")
17
18
if is_deprecated:
19
    print(f"Warning: This API version is deprecated. Sunset date: {sunset_date}")

Beta access

Beta endpoints provide early access to upcoming API changes before they are promoted to Stable. Access requires the X-Beta header.

$
curl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \
>
  -H 'Authorization: Bearer YOUR-TOKEN-HERE' \
>
  -H 'X-Beta: true'

The X-Beta header and X-Version header follow strict mutual exclusivity rules:

Backward compatibility and migration

Deel follows a predictable versioning cadence to give you time to plan and execute migrations.

• Baseline version: All existing endpoints are set to 2026-01-01, stable until at least Jan 1, 2027
• New versions: Breaking changes are introduced as new date versions (e.g., 2026-06-15). The previous version remains available throughout its lifecycle.
• Major versions: A new major version is expected approximately once per year, rolling up the latest changes
• Stability guarantee: Each version remains stable for a minimum of one year from release
• Deprecation period: Superseded versions receive exactly one year of continued support before sunset
• URL path versioning: The /v2/ URL prefix remains fully supported. Existing integrations do not need to change their URL structure.

Migration checklist

Error handling

The API returns specific error messages for versioning-related issues.

Sunset response (410 Gone)

When you request a sunset version, the API returns a 410 Gone response with migration guidance:

1
{
2
  "errors": [
3
    {
4
      "code": "endpoint_sunset",
5
      "message": "This API version has been sunset and is no longer available.",
6
      "details": {
7
        "requested_version": "2026-01-01",
8
        "latest_stable_version": "2027-01-01",
9
        "sunset_date": "2028-01-01T00:00:00.000Z"
10
      }
11
    }
12
  ]
13
}

Use latest_stable_version from the response to update your X-Version header.

1
import requests
2
import os
3
4
headers = {
5
    "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
6
    "X-Version": "2026-01-01"
7
}
8
9
response = requests.get(
10
    "https://api.letsdeel.com/rest/v2/contracts",
11
    headers=headers
12
)
13
14
if response.status_code == 410:
15
    error_data = response.json()
16
    details = error_data["errors"][0]["details"]
17
    print(f"Version {details['requested_version']} has been sunset.")
18
    print(f"Migrate to version: {details['latest_stable_version']}")
19
elif response.status_code == 400:
20
    print(f"Version error: {response.json()}")

Troubleshooting

Next steps