Skip to main content
The API has two version numbers. The major version is in the path, /v1, and changes only for a new API. The dated version is in the Reflections-Version header and changes when a release would break an integration. The current dated version is 2026-10-15.

​
Send a version

Send Reflections-Version on every request:
The discovery document lists every supported version in api_versions.

​
Pinning

Your account is pinned to the version that was current when it made its first request. The pin is what requests without the header use. A header on one request changes only that request. Webhook endpoints are pinned separately. Each endpoint renders events in its own api_version, set when you create the endpoint and defaulting to your account’s version. Every event carries the api_version it was rendered in.

​
Changes without a new date

These ship to every version, so write code that accepts them:
  • New endpoints.
  • New optional request fields and query parameters.
  • New fields in responses and events.
  • New event types. Endpoints subscribed to ["*"] receive them.
  • New values in response enums, such as a reason code. Show reasons[].sentence for a reason code you do not recognize, and deliver nothing for a generation status you do not recognize.
  • New response headers.

​
Changes that get a new date

  • Removing or renaming an endpoint, a field or an enum value.
  • Changing a field’s type, format or meaning.
  • Making an optional request field required, or changing a default.
  • A new obligation type.
Each new date ships with a migration guide in the changelog. Every dated version is supported for at least 24 months.
A new obligation type always comes with a new dated version, so a pinned integration does not receive one it was not built for. If you receive an obligation type you do not recognize, treat it as unmet: do not generate and do not deliver.

​
Upgrade

1

Read the migration guide

The changelog entry for the new date lists every change and what to do about it.
2

Test with the header

Send the new Reflections-Version from a test-mode build and run your integration tests. Use the proposed conformance cases as a guide; no hosted runner is available.
3

Move your webhooks

Create a new webhook endpoint with the new api_version, verify that it receives events, then delete the old endpoint. An endpoint’s api_version cannot be changed after it is created.
4

Move your pin

Change your account’s default version in the dashboard. Requests that send the header are not affected.

​
Protocol versions

The dated API version is separate from the version of the Talent License Protocol. Tokens and receipts carry the protocol version in tlp.ver ("1.0"), and the discovery document lists supported protocol versions in protocol_versions. See Changes to the Standard.

Changelog

Every dated version and what changed.

Webhooks

How events are rendered and delivered.