Unfortunately, this feature is not supported on mobile devices. For the best experience, please use a computer.

REST API Reference

Intercom API (2.11)

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.11

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

Example:

2.11

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

Experience it firsthand in the API Explorer!

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.11

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

Example:

2.11

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.11' \
  -d '{
    "id": 94
  }'

Experience it firsthand in the API Explorer!

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": "94",
  "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.11

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

Example:

2.11

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

Experience it firsthand in the API Explorer!

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": "97",
  "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.11

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

Example:

2.11

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.11' \
  -d '{
    "id": 99,
    "admin_id": 991267526
  }'

Experience it firsthand in the API Explorer!

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": "99",
  "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.11

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

Example:

2.11

Bodyapplication/json

admin_idstringrequired

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

Example:

"123"

Intercom API (2.11)

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