API v2 Versioning

On September 19, 2020, the NeonCRM API will add versioning to all API v2 endpoints. After this date, requests to API v2 will be able to specify an API version number with each request.

No immediate updates are required for apps using the NeonCRM API v2. Requests without a version number will default to the latest API version. However, we still recommend adding version numbers to your API v2 requests as soon as possible, to ensure the long-term stability of code that relies on this API.

If you are not a developer but you have provided an API key to a third-party app or tool that connects to your NeonCRM, contact the maker of your third-party integration to see if this change will affect you. You can provide them with the link to this page for more information.

We will introduce the first potential breaking changes to the NeonCRM API in version 2.2 on November 21, 2020. Version numbers must be included with API requests by this date in order to avoid potential disruptions to your usage of the API.

The NeonCRM API v1 will not receive versioning and is unaffected by this change.

What do I need to do?

To specify an API version number, add the following header to all API v2 requests:

  • NEON-API-VERSION: 2.1

The current API version is 2.0. The version being released on September 19, 2020 is 2.1, but there will be no breaking changes between 2.0 and 2.1. The first breaking change will occur in version 2.2 on November 21, 2020.

We recommend existing API users specify version 2.1 in order to be able to take advantage of new API endpoints being added in this version.

If you specify a version number in API requests before Sept. 19, the version number will be ignored, and the request will process normally.

What is versioning?

API versioning allows our team to release ongoing fixes and updates to the NeonCRM API while managing the impact on API users. API versioning assigns a version number to every change made to the API schema, giving API users flexibility for managing upgrades to new API versions that include breaking changes that require additional development and testing. API users specify the version of the API they want to use by adding an entry to the request header for every request to the API.

API versioning is intended to give app owners time and flexibility to re-test their integrations when upgrading to a new API version. It is not intended to allow API users to use deprecated functionality indefinitely. Older API versions are deprecated over time, but API users will be notified early and provided time to upgrade before versions are deprecated. No version deprecation is planned at this time.