API Versioning

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 you apps. You can then select the version to apply to a particular app by:

  1. Selecting it via you Developer Hub app settings page, or
  2. Setting the version on each API call via an HTTP header

Always test new version of the API

Some API versions may be breaking changes and require your 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
Choosing the API version for your app

Choosing the API version for your app

Once you have selected the appropriate version for your app all subsequent API requests will use this version.

Selecting the version via the API request

  1. 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.
  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/users?email=cathalhoran@gmail.com \
-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 version 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 if you want.

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 change 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 will also dictate which version your clients will be using. All access tokens granted via OAuth (even those granted before the change) will 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, you can, 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 version which may require you to make a change on your end

Will I always have a choice to upgrade?

Usually yes, but there may be situation related to security updates which are mandatory. 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