API versioning

Overview

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

Header versioning

The Deel API uses header-based date versioning as the standard for managing API changes. You specify a version date using the X-Version request header:

X-Version: 2026-01-01

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
• New endpoints and new versions of existing endpoints start in Beta for three months before promotion to Stable
• 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, it starts in Beta and 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.

import requests
import os
headers = {
    "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
    "X-Version": "2026-01-01"
}
response = requests.get(
    "https://api.letsdeel.com/rest/contracts",
    headers=headers
)

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.

import requests
import os
headers = {
    "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
    "X-Version": "2026-01-01"
}
response = requests.get(
    "https://api.letsdeel.com/rest/contracts",
    headers=headers
)
state = response.headers.get("X-State")
is_deprecated = response.headers.get("Deprecation") == "true"
sunset_date = response.headers.get("Sunset")
if is_deprecated:
    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.

Every new endpoint and every new version of an existing endpoint spends its first three months in Beta. During this period the owning Deel team can still change the request and response contract based on client feedback. The API reference marks these endpoints with a Beta badge and states the date on which the version is scheduled to become Stable.

curl -X GET 'https://api.letsdeel.com/rest/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 endpoints: Newly released endpoints start in Beta for three months. Access requires X-Beta: true until the endpoint is promoted to Stable.
• New versions: Breaking changes are introduced as new date versions (e.g., 2026-06-15) that start in Beta for three months. 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

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:

{
  "errors": [
    {
      "code": "endpoint_sunset",
      "message": "This API version has been sunset and is no longer available.",
      "details": {
        "requested_version": "2026-01-01",
        "latest_stable_version": "2027-01-01",
        "sunset_date": "2028-01-01T00:00:00.000Z"
      }
    }
  ]
}

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

import requests
import os
headers = {
    "Authorization": f"Bearer {os.getenv('DEEL_API_TOKEN')}",
    "X-Version": "2026-01-01"
}
response = requests.get(
    "https://api.letsdeel.com/rest/contracts",
    headers=headers
)
if response.status_code == 410:
    error_data = response.json()
    details = error_data["errors"][0]["details"]
    print(f"Version {details['requested_version']} has been sunset.")
    print(f"Migrate to version: {details['latest_stable_version']}")
elif response.status_code == 400:
    print(f"Version error: {response.json()}")

Troubleshooting

Legacy Path Versioning

The Deel API previously used URL path versioning with a /v2/ prefix in the URL:

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

This pattern is legacy but remains backward-compatible. Existing integrations that use the /v2/ URL prefix will continue to work without changes.

For new integrations, Deel recommends using header-based date versioning with the X-Version header instead of relying on the URL path prefix. Header versioning provides more granular control over which API version your integration uses.

Next steps