Update your API version

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:

  1. Selecting it via your Developer Hub app settings page, or
  2. 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

Selecting the version via the Developer Hub

  1. Go to your Developer Hub and choose the relevant app.
  2. Then go to the Basic Information menu, click on the Change version box 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 appChoosing the API version for your app

Choosing the API version for your app

Selecting the version via the API request

  1. Identify the version you want to test (e.g. 1.x or 2.x). 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.
  2. Add an HTTP header of Intercom-Version to your API request.
  3. Using the Access token for your app make an API request with the header and the appropriate version.
httpstat https://api.intercom.io/[email protected] \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Accept: application/json' \
-H 'Intercom-Version: 1.1'

Important API questions

How can I test new versions?

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.

Can I rollback after making a change?

Yes, if you select a new version for your app and you discover an issue you can switch back to an older version.

How do I switch over to a new version for my production app?

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.

Can I set the header version and the version in the app?

Yes, but the header version in the API request will override the version selected in the app.

Where can I find out information on the different versions?

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.

Will I always have a choice to upgrade?

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.

Did this page help you?