Skip to main content
Version: 2025-12-18

Versioning

This article explains how we version the Cint Exchange API, why it's important for your integration, and the types of changes you can expect across different versions.

Why we version the Cint Exchange API​

We version the API to ensure the stability and predictability of your integrations. By explicitly managing API versions, Cint can introduce new features and improvements without unexpectedly breaking existing functionalities in your applications. This approach provides you with control over when you adopt new API behaviors.

How versioning works​

We name API versions based on their release date. For example, the API version 2025-12-18 signifies a version that was released on December 18th, 2025.

To use a specific API version, you'll need to include the Cint-API-Version request header in every API call.

Mandatory version header

The Cint-API-Version header is mandatory for all requests. The API does not have a default version.

If this header is omitted, your request will fail. This policy ensures your integration is protected from unexpected changes in future API releases.

Example request with a version header:

curl GET \
  'https://api.cint.com/...' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Cint-API-Version: 2025-12-18'

Missing version header​

If you omit the Cint-API-Version header in your request, the API will respond with a 403 Forbidden error, including a message indicating that the version header is required.

Example error response for a missing version header:

{
  "id": "43da142c-13b8-4aa1-a06d-53021e6c9d72",
  "object": "required_header_missing",
  "detail": "The Cint-API-Version HTTP request header is missing. This is a required header, please try again by specifying one of our supplied API versions."
}
Why 403 Forbidden?

We use a 403 Forbidden status code to indicate that access to the API is denied without a valid version header. This policy treats versioning as a core part of access control, ensuring your integration is protected from unexpected API changes.

Deprecated and invalid versions​

If you specify a version that is no longer supported (deprecated) or one that never existed, the API will respond with a 403 Forbidden error, including a message indicating that the specified version is invalid. We recommend regularly reviewing our API Changelog to stay informed about supported versions.

Example error response for an invalid version header:

{
  "id": "f9cc6c0f-5f2d-4493-9cdc-719dca7c0a86",
  "object": "invalid_version_header",
  "detail": "The Cint-API-Version HTTP request header does not seem to match one of our supplied version header. Please check you have specified one of our supplied API versions."
}

Types of API changes​

Cint categorizes API changes into two main types:

Breaking changes​

Breaking changes are modifications to the API that can potentially disrupt or break an existing integration if you upgrade to a new version without updating your code. These changes are always released under a new API version.

Examples of breaking changes include:

  • Removing an entire API operation (e.g., an endpoint is no longer available).
  • Removing or renaming an existing parameter in a request or a response.
  • Adding a new required parameter to an existing operation.
  • Making a previously optional parameter mandatory.
  • Changing the data type of an existing parameter or a field in a response.
  • Removing specific enum values from a parameter or response field.
  • Adding a new, stricter validation rule to an existing parameter.
  • Modifying authentication or authorization requirements for an endpoint.
note

Changes to authentication are rare but are always considered breaking. We'll provide extensive advance notice for any such change.

Additive (non-breaking) changes​

Additive changes are backward-compatible and are typically rolled out to all currently supported API versions. While they introduce new functionality, they do so in a way that won't negatively impact your current integration.

Examples of additive changes include:

  • Adding an entirely new API operation or endpoint.
  • Adding an optional parameter to an existing request.
  • Adding an optional request header.
  • Adding a new, optional field to a response body.
  • Adding a new response header.
  • Adding new enum values to an existing parameter or response field (without removing existing ones).

Understanding these principles will help you plan your API updates effectively and maintain a stable, robust integration with the Cint Exchange.

Version lifecycle and deprecation​

We are committed to providing at least 12 months of support for an API version before it is deprecated. To stay up-to-date with the latest changes and upcoming deprecations, please consult our API Changelog.