Skip to main content
Imprint releases changes that could break an existing integration under a new API version, named for its release date (for example, 2025-05-05). Your integration keeps the behavior of the version it’s on until you choose to upgrade. Imprint never moves you to a new version automatically.

​
Changes that aren’t versioned

Changes that can’t break an existing integration ship to every version as soon as they’re released, without a new version:
  • New endpoints
  • New optional request fields and query parameters
  • New fields in responses and webhook payloads
Build your integration to ignore fields it doesn’t recognize, so these additions never affect it.

​
Changes that are versioned

Changes that could break an integration always ship in a new version. These include:
  • Removing or renaming a field
  • Changing a field’s type or format
  • Changing a status code or error type
  • Adding a new value to an enum in a response or webhook payload, such as a new status on a webhook event
  • Adding new validation to a request
For example, if a new application status is added to application webhooks, only integrations on the version that introduces it receive the new status. Integrations on earlier versions keep receiving only the statuses they already handle.

​
How the version for a request is chosen

For every request, the API uses:
  1. The version in the x-imprint-version request header, if you send one.
  2. Otherwise, the version saved for your account in the Imprint Dashboard.
Once a request has a version, its response includes an x-imprint-version header with that version, so you can confirm which behavior you received. This includes error responses from the endpoint itself.
Responses to requests rejected before a version is chosen don’t include the header. That covers authentication errors and requests with an unsupported x-imprint-version value.

​
Set your version in the Imprint Dashboard

Your saved version applies to every request from your account that doesn’t send the x-imprint-version header.
1

Open the API version setting

In the Imprint Dashboard, choose the environment (sandbox or production), then go to Developers → API version. The page shows your saved version and the version your requests are served.
2

Choose a version

Select the version you want. Production lists released versions only. Sandbox also lists latest, which contains changes that haven’t been released yet (see Test upcoming changes in sandbox).
3

Save

The new version applies to your next request. To roll back, select your previous version and save again.
Any user on your account can view the API version, but only users with the Admin role can change it. Sandbox and production are set separately, so changing one doesn’t affect the other.

​
Send a version on a request

To use a different version for a single request without changing your saved version, send the x-imprint-version header:
The header overrides your saved version for that request only. This is the safest way to test an upgrade: send the new version on a few requests, check the results, then change your saved version in the Imprint Dashboard. The header name isn’t case-sensitive, but the value must be exactly a released version, such as 2025-05-05, or latest in sandbox.

​
Unsupported versions

A request with a version that isn’t supported fails with 400, and the message lists the versions you can use. Because no version was chosen, this response doesn’t include an x-imprint-version header.

​
Test upcoming changes in sandbox

Changes that haven’t been released yet are available in sandbox only, under the version latest. To try them, either:
  • send x-imprint-version: latest on individual sandbox requests, or
  • select latest as your sandbox version in the Imprint Dashboard.
Upcoming changes are documented in the unreleased docs preview: pick latest in its version selector to see the upcoming API reference, and open its changelog for the list of upcoming changes.

​
Upgrade to a new version

1

Read what changed

The changelog lists every version and its breaking changes. Read each entry newer than your current version. You can subscribe to it as an RSS feed to hear about new versions.
2

Test in sandbox

Send x-imprint-version with the new version on your sandbox requests, and update your integration for any changes.
3

Switch sandbox

Select the new version as your sandbox version in the Imprint Dashboard, and run your sandbox tests without the header.
4

Switch production

Select the new version as your production version. If anything goes wrong, switch back to your previous version.

​
Versions in the API reference

The API reference has a version selector at the top of the sidebar. Each released version has its own reference, so you can read exactly the behavior of the version your integration uses.