API versioning

Learn about API versioning at Numeral

1. API versioning at Numeral

Numeral uses versioning to introduce breaking changes without impacting live customers. Breaking changes include changes such as:

  • An attribute being renamed
  • An attribute being removed
  • An attribute format being changed
  • A new logic being implemented for an existing feature

API versions are numbered using their release date (e.g., 2023-04-12). API versions are maintained for a minimum of 12 months after a new API version is released.

New customers and new API keys for existing customers are linked to the latest API version. Existing customers and API keys are automatically migrated to the latest API version 90 days after it has been released. They can force a specific version of the API by setting it in their API requests.

New features and improvements to existing features are only available in the latest API version.

The public documentation refers to the latest API version.

2. API versions

VersionChangelogDefault version date after
2023-04-12Changelog API version 2023-04-12May 24, 2023

3. Setting the API version

To use a specific version of the API, use the Numeral-Api-Version HTTP header of your API requests as follows:

curl --request GET \
     --url 'https://sandbox.numeral.io/v1/payment_orders?limit=25' \
     --header 'accept: application/json' \
     --header 'x-api-key: 279413050bb4455e9ae4dfb0bdf210fd' \
     --header 'numeral-api-version: 2023-04-12'