Platform

API Versions

Copy page

The Dossiers API is versioned by date. A Cloud API version such as 2026-10-01 names the request, response and webhook payload shapes your integration was built against. It changes only when something breaks — never for additions.

Sending your version

Name the version you were built against in the Dossiers-Api-Version header of every request:

Code
curl https://api.dossiers.wiki/kyc-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Dossiers-Api-Version: 2026-10-01"

The @dossier-wiki/cloud-sdk sends it for you: each SDK release pins one version, exported as DOSSIERS_API_VERSION.

A request without the header is served as 2026-10-01, the first dated version.

Supported versions

Version	Status
2026-10-01	Current

What can change within a version

Within one version, changes are additive only: new endpoints, new optional request fields, new response fields, new webhook event types. Nothing is removed, renamed or retyped.

So your integration must:

• Ignore response and payload fields it does not know.
• Acknowledge webhook event types it does not know with a 2xx and do nothing. The SDK's DossiersWebhookRouter does this for you.

A breaking change ships as a new dated version. The old version keeps working, unchanged, until its sunset date.

Deprecation

When your version is deprecated, every response carries:

Header	Meaning
Deprecation	When the version was deprecated, as @ + Unix seconds (RFC 9745)
Sunset	When the version stops being served, as an HTTP date (RFC 8594)
Link	<https://docs.dossiers.wiki/api-versions>; rel="deprecation"

The SDK reports these through the onContractNotice option:

Code
const service = new DossiersAPIService({
  apiKey: process.env.DOSSIERS_API_KEY!,
  onContractNotice: (notice) => alertOps(notice), // { apiVersion, status, deprecation, sunset, link }
});

Errors

Status	Meaning
400 Bad Request	The version is not one the API knows — a typo, or newer than the API. The body lists supportedVersions.
426 Upgrade Required	The version is past its sunset. Upgrade your integration to minimumApiVersion or later.

Code
{
  "statusCode": 426,
  "error": "Upgrade Required",
  "message": "Dossiers-Api-Version \"2025-01-01\" is no longer supported. ...",
  "minimumApiVersion": "2026-10-01"
}

The SDK throws DossiersUpgradeRequiredError on a 426.

Webhooks

Each webhook destination has its own API version. Deliveries are shaped for it, carry it in the payload's apiVersion field, and send it as the Dossiers-Api-Version header. See Webhooks.

Identifying your integration

Optionally, tell us what is calling, so support can see which build of your integration holds each key. This never changes how the API behaves.

Header	Example
User-Agent	my-app/2.3.1 (4f2a9c1e) cloud-sdk/0.8.0 node/22.19.0
Dossiers-Installation-Id	A stable id for the deployment making the call

With the SDK, pass appInfo: { name, version, commit?, installationId? }. The last client seen on each key is shown in the Developer Console.