API -> Untag multiple contacts

  • 13 February 2024
  • 1 reply


I’ve been successfully using the Intercom API to tag multiple contacts at once using the /tags endpoint. However, I’m now facing a challenge: I need to remove tags from multiple contacts, but I can’t find a straightforward solution in the documentation.

Here’s the snippet I’ve been using to tag contacts:

const resp = await fetch(
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Intercom-Version': '2.10',
Authorization: 'Bearer <YOUR_TOKEN_HERE>'
body: JSON.stringify({name: 'test', users: [{ id: 'userId1' }, { id: 'userId2' }] })


Now, I’d like to perform the reverse operation: remove tags from multiple contacts. Is there an equivalent endpoint for this task? I’ve checked the documentation, but it seems that the /contacts/{contact_id}/tags endpoint is not suitable for bulk removal due to potential API rate limits.

Any guidance or pointers would be greatly appreciated!





Best answer by bernice 19 February 2024, 15:38

View original

1 reply

Userlevel 3
Badge +3

Hey @Kirill 👋 To bulk untag contacts, you can follow these steps:

You’ll need to get the entire list of contacts and then remove each contact from being tagged. You'll need the tag_id, which can be found by getting all tags and searching for the tag by name to get the id. You can find more information on the Intercom API documentation: List Contacts, Detach Tag from Contact, and List Tags.

The default limit is 1000 requests per minute, however, to prevent large spikes in traffic it's distributed over 10 second periods (so 166 operations per 10 seconds).

If you are exceeding this rate limit you'll be alerted by a HTTP 429 response code. We aren't necessarily able to increase the limit since its purpose is to prevent spiking our servers, however, we can look at helping you better combat this in the future.

Our API Reference doc has details on the headers that are returned in each request to help give more details into rate limits. You could even use those headers to determine when the rate limit will be reset.

​If you don't need to keep the tag on any users, you can simply delete the tag from Settings > Company data > Tags.

Hope this helps! 🚀