API Reference
Log inContact us

API versioning

1. 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:

  • 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 maintained until all customers have migrated to the latest API version.

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 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.

2. API versions

VersionChangelogAPI documentationDefault version date after
2023-04-12Changelog API version 2023-04-12API documentation version 2023-04-12May 24, 2023

3. 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'