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 Export

Everything about your Data Exports

Operations

Data Export

The data export api is used to view all message sent & viewed in a given timeframe.

job_identfierstring

The identifier for your job.

Example: "orzzsbd7hk67xyu"
statusstring

The current state of your job.

Enum"pending""in_progress""failed""completed""no_data""canceled"
Example: "pending"
download_expires_atstring

The time after which you will not be able to access the data.

Example: "1674917488"
download_urlstring

The location where you can download your data.

Example: "https://api.intercom.test/download/messages/data/example"
{ "job_identfier": "orzzsbd7hk67xyu", "status": "pending", "download_expires_at": "1674917488", "download_url": "https://api.intercom.test/download/messages/data/example" }

Create content data export

Request

To create your export job, you need to send a POST request to the export endpoint https://api.intercom.io/export/content/data.

The only parameters you need to provide are the range of dates that you want exported.

🚧 Limit of one active job

You can only have one active job per workspace. You will receive a HTTP status code of 429 with the message Exceeded rate limit of 1 pending message data export jobs if you attempt to create a second concurrent job.

❗️ Updated_at not included

It should be noted that the timeframe only includes messages sent during the time period and not messages that were only updated during this period. For example, if a message was updated yesterday but sent two days ago, you would need to set the created_at_after date before the message was sent to include that in your retrieval job.

📘 Date ranges are inclusive

Requesting data for 2018-06-01 until 2018-06-30 will get all data for those days including those specified - e.g. 2018-06-01 00:00:00 until 2018-06-30 23:59:99.

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
created_at_afterintegerrequired

The start date that you request data for. It must be formatted as a unix timestamp.

Example: 1527811200
created_at_beforeintegerrequired

The end date that you request data for. It must be formatted as a unix timestamp.

Example: 1527811200
curl -i -X POST \
  https://api.intercom.io/export/content/data \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.11' \
  -d '{
    "created_at_after": 1719474967,
    "created_at_before": 1719492967
  }'

Responses

successful

Bodyapplication/json
job_identfierstring

The identifier for your job.

Example: "orzzsbd7hk67xyu"
statusstring

The current state of your job.

Enum"pending""in_progress""failed""completed""no_data""canceled"
Example: "pending"
download_expires_atstring

The time after which you will not be able to access the data.

Example: "1674917488"
download_urlstring

The location where you can download your data.

Example: "https://api.intercom.test/download/messages/data/example"
Response
application/json
{ "job_identifier": "bxe9awlish03jkq8", "status": "pending", "download_url": "", "download_expires_at": "" }

Show content data export

Request

You can view the status of your job by sending a GET request to the URL https://api.intercom.io/export/content/data/{job_identifier} - the {job_identifier} is the value returned in the response when you first created the export job. More on it can be seen in the Export Job Model.

🚧 Jobs expire after two days All jobs that have completed processing (and are thus available to download from the provided URL) will have an expiry limit of two days from when the export ob completed. After this, the data will no longer be available.

Path
job_identifierstringrequired

job_identifier

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/export/content/data/{job_identifier}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.11'

Responses

successful

Bodyapplication/json
job_identfierstring

The identifier for your job.

Example: "orzzsbd7hk67xyu"
statusstring

The current state of your job.

Enum"pending""in_progress""failed""completed""no_data""canceled"
Example: "pending"
download_expires_atstring

The time after which you will not be able to access the data.

Example: "1674917488"
download_urlstring

The location where you can download your data.

Example: "https://api.intercom.test/download/messages/data/example"
Response
application/json
{ "job_identifier": "b1ppo8h93fj386fk", "status": "pending", "download_url": "", "download_expires_at": "" }

Cancel content data export

Request

You can cancel your job

Path
job_identifierstringrequired

job_identifier

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 POST \
  'https://api.intercom.io/export/cancel/{job_identifier}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.11'

Responses

successful

Bodyapplication/json
job_identfierstring

The identifier for your job.

Example: "orzzsbd7hk67xyu"
statusstring

The current state of your job.

Enum"pending""in_progress""failed""completed""no_data""canceled"
Example: "pending"
download_expires_atstring

The time after which you will not be able to access the data.

Example: "1674917488"
download_urlstring

The location where you can download your data.

Example: "https://api.intercom.test/download/messages/data/example"
Response
application/json
{ "job_identifier": "pwrbmmimhakvlfsh", "status": "canceled", "download_url": "", "download_expires_at": "" }

Download content data export

Request

When a job has a status of complete, and thus a filled download_url, you can download your data by hitting that provided URL, formatted like so: https://api.intercom.io/download/content/data/xyz1234.

Your exported message data will be streamed continuously back down to you in a gzipped CSV format.

📘 Octet header required

You will have to specify the header Accept: application/octet-stream when hitting this endpoint.

Path
job_identifierstringrequired

job_identifier

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/download/content/data/{job_identifier}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.11'

Responses

successful

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