REST API Reference

Intercom API (2.7)

The intercom API reference.

Download OpenAPI description

api.intercom.io.json

api.intercom.io.yaml

Overview

URL https://developers.intercom.com

License MIT

Servers

The production API server

https://api.intercom.io/

The european API server

https://api.eu.intercom.io/

The australian API server

https://api.au.intercom.io/

Admins

Everything about your Admins

Operations

Articles

Everything about your Articles

Operations

Companies

Everything about your Companies

Operations

Contacts

Everything about your contacts

Operations

Conversations

Everything about your Conversations

Operations

Data Attributes

Everything about your Data Attributes

Operations

Data Events

Everything about your Data Events

Operations

Data Export

Everything about your Data Exports

Operations

Help Center

Everything about your Help Center

Operations

Messages

Everything about your messages

Operations

News

Everything about your News

Operations

Notes

Everything about your Notes

Operations

Segments

Everything about your Segments

Operations

Subscription Types

Everything about subscription types

Operations

Switch

Everything about Switch

Operations

Tag

A tag allows you to label your contacts, companies, and conversations and list them using that tag.

typestring

value is "tag"

Example: "tag"

idstring

The id of the tag

Example: "123456"

namestring

The name of the tag

Example: "Test tag"

applied_atinteger(date-time)

The time when the tag was applied to the object

Example: 1663597223

applied_byobject(Reference)

reference to another object

{
  "type": "tag",
  "id": "123456",
  "name": "Test tag",
  "applied_at": 1663597223,
  "applied_by": {
    "type": "contact",
    "id": "1a2b3c"
  }
}

List tags attached to a contact

Request

You can fetch a list of all tags that are attached to a specific contact.

Path

contact_idstringrequired

The unique identifier for the contact which is given by Intercom

Example: 63a07ddf05a32042dffac965

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.7

Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example: 2.7

curl -i -X GET \
  'https://api.intercom.io/contacts/{contact_id}/tags' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.7'

Responses

successful

Bodyapplication/json

typestring

The type of the object

Value"list"

Example: "list"

dataArray of objects(Tag)

A list of tags objects associated with the workspace .

Response

application/json

{
  "type": "list",
  "data": [
    { … }
  ]
}

Add tag to a contact

Request

You can tag a specific contact. This will return a tag object for the tag that was added to the contact.

Path

contact_idstringrequired

The unique identifier for the contact which is given by Intercom

Example: 63a07ddf05a32042dffac965

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.7

Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example: 2.7

Bodyapplication/json

idstringrequired

The unique identifier for the tag which is given by Intercom

Example: "7522907"

curl -i -X POST \
  'https://api.intercom.io/contacts/{contact_id}/tags' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.7' \
  -d '{
    "id": 2
  }'

Responses

successful

Bodyapplication/json

typestring

value is "tag"

Example: "tag"

idstring

The id of the tag

Example: "123456"

namestring

The name of the tag

Example: "Test tag"

applied_atinteger(date-time)

The time when the tag was applied to the object

Example: 1663597223

applied_byobject(Reference)

reference to another object

Response

application/json

{
  "type": "tag",
  "id": "2",
  "name": "Manual tag"
}

Remove tag from a contact

Request

You can remove tag from a specific contact. This will return a tag object for the tag that was removed from the contact.

Path

contact_idstringrequired

The unique identifier for the contact which is given by Intercom

Example: 63a07ddf05a32042dffac965

idstringrequired

The unique identifier for the tag which is given by Intercom

Example: 7522907

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.7

Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example: 2.7

curl -i -X DELETE \
  'https://api.intercom.io/contacts/{contact_id}/tags/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.7'

Responses

successful

Bodyapplication/json

typestring

value is "tag"

Example: "tag"

idstring

The id of the tag

Example: "123456"

namestring

The name of the tag

Example: "Test tag"

applied_atinteger(date-time)

The time when the tag was applied to the object

Example: 1663597223

applied_byobject(Reference)

reference to another object

Response

application/json

{
  "type": "tag",
  "id": "5",
  "name": "Manual tag"
}

Add tag to a conversation

Request

You can tag a specific conversation. This will return a tag object for the tag that was added to the conversation.

Path

conversation_idstringrequired

conversation_id

Example: 64619700005694

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.7

Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example: 2.7

Bodyapplication/json

idstringrequired

The unique identifier for the tag which is given by Intercom

Example: "7522907"

admin_idstringrequired

The unique identifier for the admin which is given by Intercom.

Example: "780"

curl -i -X POST \
  'https://api.intercom.io/conversations/{conversation_id}/tags' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.7' \
  -d '{
    "id": 7,
    "admin_id": 991266359
  }'

Responses

successful

Bodyapplication/json

typestring

value is "tag"

Example: "tag"

idstring

The id of the tag

Example: "123456"

namestring

The name of the tag

Example: "Test tag"

applied_atinteger(date-time)

The time when the tag was applied to the object

Example: 1663597223

applied_byobject(Reference)

reference to another object

Response

application/json

{
  "type": "tag",
  "id": "7",
  "name": "Manual tag"
}

Remove tag from a conversation

Request

You can remove tag from a specific conversation. This will return a tag object for the tag that was removed from the conversation.

Path

conversation_idstringrequired

conversation_id

Example: 64619700005694

idstringrequired

Example: 7522907

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.7

Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example: 2.7

Bodyapplication/json

admin_idstringrequired

The unique identifier for the admin which is given by Intercom.

Example: "123"

curl -i -X DELETE \
  'https://api.intercom.io/conversations/{conversation_id}/tags/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.7' \
  -d '{
    "admin_id": 991266363
  }'

Responses

successful

Bodyapplication/json

typestring

value is "tag"

Example: "tag"

idstring

The id of the tag

Example: "123456"

namestring

The name of the tag

Example: "Test tag"

applied_atinteger(date-time)

The time when the tag was applied to the object

Example: 1663597223

applied_byobject(Reference)

reference to another object

Response

application/json

{
  "type": "tag",
  "id": "10",
  "name": "Manual tag"
}

Create or update a tag, Tag or untag companies, Tag contacts

Request

You can use this endpoint to perform the following operations:

1. Create a new tag: You can create a new tag by passing in the tag name as specified in "Create or Update Tag Request Payload" described below.

2. Update an existing tag: You can update an existing tag by passing the id of the tag as specified in "Create or Update Tag Request Payload" described below.

3. Tag Companies: You can tag single company or a list of companies. You can tag a company by passing in the tag name and the company details as specified in "Tag Company Request Payload" described below. Also, if the tag doesn't exist then a new one will be created automatically.

4. Untag Companies: You can untag a single company or a list of companies. You can untag a company by passing in the tag id and the company details as specified in "Untag Company Request Payload" described below.

5. Tag Multiple Users: You can tag a list of users. You can tag the users by passing in the tag name and the user details as specified in "Tag Users Request Payload" described below.

Each operation will return a tag object.

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.7

Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example: 2.7

Bodyapplication/json

One of:

You can create or update an existing tag.

namestringrequired

The name of the tag, which will be created if not found, or the new name for the tag if this is an update request. Names are case insensitive.

Example: "Independent"

idstring

The id of tag to updates.

Example: "656452352"

curl -i -X POST \
  https://api.intercom.io/tags \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.7' \
  -d '{
    "name": "test"
  }'

Responses

Action successful

Bodyapplication/json

typestring

value is "tag"

Example: "tag"

idstring

The id of the tag

Example: "123456"

namestring

The name of the tag

Example: "Test tag"

applied_atinteger(date-time)

The time when the tag was applied to the object

Example: 1663597223

applied_byobject(Reference)

reference to another object

Response

application/json

{
  "type": "tag",
  "id": "26",
  "name": "test"
}

Find a specific tag

Request

You can fetch the details of tags that are on the workspace by their id. This will return a tag object.

Path

idstringrequired

The unique identifier of a given tag

Example: 123

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.7

Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example: 2.7

curl -i -X GET \
  'https://api.intercom.io/tags/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.7'

Responses

Tag found

Bodyapplication/json

typestring

value is "tag"

Example: "tag"

idstring

The id of the tag

Example: "123456"

namestring

The name of the tag

Example: "Test tag"

applied_atinteger(date-time)

The time when the tag was applied to the object

Example: 1663597223

applied_byobject(Reference)

reference to another object

Response

application/json

{
  "type": "tag",
  "id": "34",
  "name": "Manual tag"
}

Delete tag

Request

You can delete the details of tags that are on the workspace by passing in the id.

Path

idstringrequired

The unique identifier of a given tag

Example: 123

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.7

Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example: 2.7

curl -i -X DELETE \
  'https://api.intercom.io/tags/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.7'

Responses

Successful

Response

application/json

{
  "type": "error.list",
  "request_id": "2a5a7cf1-fbbd-426d-a997-300e2ff0280b",
  "errors": [
    { … }
  ]
}

Teams

Everything about your Teams

Operations

Visitors

Everything about your Visitors

Operations

Intercom API (2.7)

Admins

Articles

Companies

Contacts

Conversations

Data Attributes

Data Events

Data Export

Help Center

Messages

News

Notes

Segments

Subscription Types

Switch

Tags

Tag

List tags attached to a contact

Request

Responses

Was this page helpful?

Add tag to a contact

Request

Responses

Was this page helpful?

Remove tag from a contact

Request

Responses

Was this page helpful?

Add tag to a conversation

Request

Responses

Was this page helpful?

Remove tag from a conversation

Request

Responses

Was this page helpful?

List all tags

Request

Responses

Was this page helpful?

Create or update a tag, Tag or untag companies, Tag contacts

Request

Responses

Was this page helpful?

Find a specific tag

Request

Responses

Was this page helpful?

Delete tag

Request

Responses

Was this page helpful?

Teams

Visitors

Models