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
Version | Changelog | Default version date after |
---|---|---|
2023-04-12 | Changelog API version 2023-04-12 | May 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'