API versions apply to your apps so you can choose which version you want to apply to which app. You can go to your Developer Hub page to see the list of your apps. You can then select the version to apply to a particular app by:
- Selecting it via your
Developer Hubapp settings page, or
- Setting the version on each API call via an HTTP header
Always test new versions of the API
Some API versions may be breaking changes and require you to change your code if you are using that feature. We will highlight this when we provide information on the new version but you should always test new versions of the API to ensure they are fully compatible with your system
- Go to your Developer Hub and choose the relevant app.
- Then go to the
Basic Informationmenu, click on the
Change versionbox and select your new version. Once you have selected the appropriate version for your app all subsequent API requests will use this version.
Choosing the API version for your app
- Identify the version you want to test (e.g. 1.x or 1.y). You can check the change log or look at the available versions in the app dropdown above to confirm the version number you want to use.
- Add an HTTP header of
Intercom-Versionto your API request.
- Using the
Access tokenfor your app make an API request with the header and the appropriate version.
httpstat https://firstname.lastname@example.org \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Accept: application/json' \ -H 'Intercom-Version: 1.1'
The best way to test new versions of the API is by setting the version in a HTTP header. That way you can check what has changed and see whether it is compatible with your code, or whether you need to make a change before adopting the new version.
Yes, if you select a new version for your app and you discover an issue you can switch back to an older version.
You can start by setting the version via the HTTP header. This way you can ship code to production which changes the version and any new code needed at the same time. Once this is working in production you can change the version in your app and then remove the headers if you like.
For OAuth apps, this setting also dictates which version your clients use. All access tokens granted via OAuth (even those granted before the change) use the version that you have specified in your app settings and/or HTTP header.
Yes, but the header version in the API request will override the version selected in the app.
The change log is the best place to find information on the different versions and the changes they contain. We will highlight breaking changes in the change log clearly so you are aware of versions that may require you to make a change on your end.
Usually, but there may be security updates which necessitate mandatory changes. In these cases we will attempt to minimize any impact on older versions. For example, if we have to remove an attribute we will do that in the new version and may only change the value in older versions so as to minimize the impact until you upgrade to the newer version.