API versioning at Numeral

Numeral uses versioning to introduce breaking changes without impacting live customers. Versions are numbered using their release date (e.g., 2023-04-12).

Breaking changes include changes such as:

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

API versions are maintained until all customers have migrated to the latest API version.

New customers and new API keys are linked to the latest API version.

Existing customers and API keys are automatically migrated to the latest API version 45 days after it has been released.

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

The public documentation refers to the latest API version. The documentation of previous API versions can be found in the API versions table below.

API versions

Version	Changelog	API documentation	Default version date after
`2023-04-12`	Changelog API version 2023-04-12	API documentation version 2023-04-12	May 24, 2023
`2022-01-01`	N/A	API documentation version 2022-01-01	N/A

Setting the API version

If you would like to use a specific version of the API, you can do so by setting the version in 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'