Intercom API (2.11)

The intercom API reference.

Download OpenAPI description
Languages
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 Event

Data events are used to notify Intercom of changes to your data.

typestring

The type of the object

Value"event"
Example: "event"
event_namestringrequired

The name of the event that occurred. This is presented to your App's admins when filtering and creating segments - a good event name is typically a past tense 'verb-noun' combination, to improve readability, for example updated-plan.

Example: "invited-friend"
created_atinteger(date-time)required

The time the event occurred as a UTC Unix timestamp

Example: 1671028894
user_idstring

Your identifier for the user.

Example: "314159"
idstring

Your identifier for a lead or a user.

Example: "8a88a590-e1c3-41e2-a502-e0649dbf721c"
intercom_user_idstring

The Intercom identifier for the user.

Example: "63a0979a5eeebeaf28dd56ba"
emailstring

An email address for your user. An email should only be used where your application uses email to uniquely identify users.

Example: "frodo.baggins@example.com"
metadataobject

Optional metadata about the event.

Example: {"invite_code":"ADDAFRIEND"}
{ "type": "event", "event_name": "invited-friend", "created_at": 1671028894, "user_id": "314159", "id": "8a88a590-e1c3-41e2-a502-e0649dbf721c", "intercom_user_id": "63a0979a5eeebeaf28dd56ba", "email": "frodo.baggins@example.com", "metadata": { "invite_code": "ADDAFRIEND" } }

Submit a data event

Request

You will need an Access Token that has write permissions to send Events. Once you have a key you can submit events via POST to the Events resource, which is located at https://api.intercom.io/events, or you can send events using one of the client libraries. When working with the HTTP API directly a client should send the event with a Content-Type of application/json.

When using the JavaScript API, adding the code to your app makes the Events API available. Once added, you can submit an event using the trackEvent method. This will associate the event with the Lead or currently logged-in user or logged-out visitor/lead and send it to Intercom. The final parameter is a map that can be used to send optional metadata about the event.

With the Ruby client you pass a hash describing the event to Intercom::Event.create, or call the track_user method directly on the current user object (e.g. user.track_event).

NB: For the JSON object types, please note that we do not currently support nested JSON structure.

TypeDescriptionExample
StringThe value is a JSON String"source":"desktop"
NumberThe value is a JSON Number"load": 3.67
DateThe key ends with the String _date and the value is a Unix timestamp, assumed to be in the UTC timezone."contact_date": 1392036272
LinkThe value is a HTTP or HTTPS URI."article": "https://example.org/ab1de.html"
Rich LinkThe value is a JSON object that contains url and value keys."article": {"url": "https://example.org/ab1de.html", "value":"the dude abides"}
Monetary AmountThe value is a JSON object that contains amount and currency keys. The amount key is a positive integer representing the amount in cents. The price in the example to the right denotes €349.99."price": {"amount": 34999, "currency": "eur"}

Lead Events

When submitting events for Leads, you will need to specify the Lead's id.

Metadata behaviour

  • We currently limit the number of tracked metadata keys to 10 per event. Once the quota is reached, we ignore any further keys we receive. The first 10 metadata keys are determined by the order in which they are sent in with the event.
  • It is not possible to change the metadata keys once the event has been sent. A new event will need to be created with the new keys and you can archive the old one.
  • There might be up to 24 hrs delay when you send a new metadata for an existing event.

Event de-duplication

The API may detect and ignore duplicate events. Each event is uniquely identified as a combination of the following data - the Workspace identifier, the Contact external identifier, the Data Event name and the Data Event created time. As a result, it is strongly recommended to send a second granularity Unix timestamp in the created_at field.

Duplicated events are responded to using the normal 202 Accepted code - an error is not thrown, however repeat requests will be counted against any rate limit that is in place.

HTTP API Responses

  • Successful responses to submitted events return 202 Accepted with an empty body.
  • Unauthorised access will be rejected with a 401 Unauthorized or 403 Forbidden response code.
  • Events sent about users that cannot be found will return a 404 Not Found.
  • Event lists containing duplicate events will have those duplicates ignored.
  • Server errors will return a 500 response code and may contain an error message in the body.
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
Any of:
event_namestringrequired

The name of the event that occurred. This is presented to your App's admins when filtering and creating segments - a good event name is typically a past tense 'verb-noun' combination, to improve readability, for example updated-plan.

Example: "invited-friend"
created_atinteger(date-time)required

The time the event occurred as a UTC Unix timestamp

Example: 1671028894
user_idstring

Your identifier for the user.

Example: "314159"
idstringrequired

The unique identifier for the contact (lead or user) which is given by Intercom.

Example: "8a88a590-e1c3-41e2-a502-e0649dbf721c"
emailstring

An email address for your user. An email should only be used where your application uses email to uniquely identify users.

Example: "frodo.baggins@example.com"
metadataobject

Optional metadata about the event.

Example: {"invite_code":"ADDAFRIEND"}
curl -i -X POST \
  https://api.intercom.io/events \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.11' \
  -d '{
    "event_name": "invited-friend",
    "created_at": 1671028894,
    "user_id": "314159",
    "id": "8a88a590-e1c3-41e2-a502-e0649dbf721c",
    "email": "frodo.baggins@example.com",
    "metadata": {
      "invite_code": "ADDAFRIEND"
    }
  }'

Responses

successful

Response
application/json
{ "type": "error.list", "request_id": "c6b3dcbd-33be-4a80-abb4-c5b3315250d0", "errors": [ { … } ] }

List all data events

Request

🚧

Please note that you can only 'list' events that are less than 90 days old. Event counts and summaries will still include your events older than 90 days but you cannot 'list' these events individually if they are older than 90 days

The events belonging to a customer can be listed by sending a GET request to https://api.intercom.io/events with a user or lead identifier along with a type parameter. The identifier parameter can be one of user_id, email or intercom_user_id. The type parameter value must be user.

  • https://api.intercom.io/events?type=user&user_id={user_id}
  • https://api.intercom.io/events?type=user&email={email}
  • https://api.intercom.io/events?type=user&intercom_user_id={id} (this call can be used to list leads)

The email parameter value should be url encoded when sending.

You can optionally define the result page size as well with the per_page parameter.

Query
filteruser_id query parameter (object) or intercom_user_id query parameter (object) or email query parameter (object)required
One of:
filter.​user_idstringrequired
typestringrequired

The value must be user

summaryboolean

summary flag

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/events?summary=true&type=string&user_id=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.11'

Responses

Successful response

Bodyapplication/json
typestring

The type of the object

Value"event.summary"
Example: "event.summary"
emailstring

The email address of the user

Example: "Sam.Sung@example.com"
intercom_user_idstring

The Intercom user ID of the user

Example: "63a0979a5eeebeaf28dd56ba"
user_idstring

The user ID of the user

Example: "62b997f288e14803c5006932"
eventsArray of objects or null(Data Event Summary Item)

A summary of data events

Response
application/json
{ "type": "event.summary", "events": [], "pages": { "next": "http://api.intercom.test/events?next page" }, "email": "user26@email.com", "intercom_user_id": "667d61648a68186f43bafe4b", "user_id": "3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3" }

Create event summaries

Request

Create event summaries for a user. Event summaries are used to track the number of times an event has occurred, the first time it occurred and the last time it occurred.

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
user_idstring

Your identifier for the user.

Example: "314159"
event_summariesobject

A list of event summaries for the user. Each event summary should contain the event name, the time the event occurred, and the number of times the event occurred. The event name should be a past tense 'verb-noun' combination, to improve readability, for example updated-plan.

curl -i -X POST \
  https://api.intercom.io/events/summaries \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.11' \
  -d '{
    "user_id": "314159",
    "event_summaries": {
      "event_name": "invited-friend",
      "count": 1,
      "first": 1671028894,
      "last": 1671028894
    }
  }'

Responses

successful

Response
application/json
{ "type": "error.list", "request_id": "110801d1-2f7b-436f-8f03-2245545a1432", "errors": [ { … } ] }

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

Tags

Everything about tags

Operations

Teams

Everything about your Teams

Operations

Ticket Type Attributes

Everything about your ticket type attributes

Operations

Ticket Types

Everything about your ticket types

Operations

Tickets

Everything about your tickets

Operations

Visitors

Everything about your Visitors

Operations