The intercom API reference.
URL https://developers.intercom.com
License MIT
The intercom API reference.
With the AI Content APIs, you can create and manage External Pages and Content Import Sources for your Fin Content Library.
External Pages are pages that you want Fin to be able to answer questions about. The API for External Pages is a great way to ingest into your Fin Content Library pages that are not publicly accessible and hence can't be crawled by Intercom.
Content Import Sources are the sources of those pages, and they are used to determine the default audience for the pages (configured via the UI). You should create a Content Import Source for each source of External Pages that you want to ingest into your Fin Content Library.
You can then iterate through the content from that source via its API and POST it to the External Pages endpoint. That endpoint has an external_id parameter which allows you to specify the identifier from the source. The endpoint will then either create a new External Page or update an existing one as appropriate.",
Tickets are how you track requests from your users.
The ID of the Ticket used in the Intercom Inbox and Messenger. Do not use ticket_id for API queries.
An object containing the different attributes associated to the ticket as key-value pairs. For the default title and description attributes, the keys are _default_title_ and _default_description_.
A ticket type, used to define the data fields to be captured in a ticket.
The time the ticket was created as a UTC Unix timestamp.
The last time the ticket was updated as a UTC Unix timestamp.
The time the ticket will be snoozed until as a UTC Unix timestamp. If null, the ticket is not currently snoozed.
An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.
A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts.
{ "type": "ticket", "id": "1295", "ticket_id": "1390", "category": "Customer", "ticket_attributes": { "_default_title_": "Found a bug", "_default_description_": "The button's not working" }, "ticket_state": { "type": "ticket_state", "id": "12", "category": "in_progress", "internal_label": "With Dev Team", "external_label": "In Progress" }, "ticket_type": { "type": "ticket_type", "id": "1295", "category": "Customer", "name": "Bug", "description": "A bug that has been reported.", "icon": "🐞", "workspace_id": "ecahpwf5", "ticket_type_attributes": { … }, "ticket_states": { … }, "archived": false, "created_at": 0, "updated_at": 0 }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "admin_assignee_id": "1295", "team_assignee_id": "1295", "created_at": 1663597223, "updated_at": 1663597260, "open": true, "snoozed_until": 1663597260, "linked_objects": { "type": "list", "total_count": 100, "has_more": false, "data": [ … ] }, "ticket_parts": { "type": "ticket_part.list", "ticket_parts": [ … ], "total_count": 2 }, "is_shared": true }
A Ticket Part represents a message in the ticket.
The previous state of the ticket.
The state of the ticket.
The author that wrote or triggered the part. Can be a bot, admin, team or user.
{ "type": "ticket_part", "id": "3", "part_type": "comment", "body": "<p>Okay!</p>", "previous_ticket_state": "submitted", "ticket_state": "submitted", "created_at": 1663597223, "updated_at": 1663597260, "assigned_to": { "type": "contact", "id": "1a2b3c" }, "author": { "type": "admin", "id": "274", "name": "Operator", "email": "operator+abcd1234@intercom.io" }, "attachments": [ { … } ], "external_id": "abcd1234", "redacted": false }
A ticket state, used to define the state of a ticket.
String representing the object's type. Always has the value ticket_state.
The category of the ticket state
The state the ticket is currently in, in a human readable form - visible in Intercom
{ "type": "ticket_state", "id": "12", "category": "in_progress", "internal_label": "With Dev Team", "external_label": "In Progress" }
A ticket state, used to define the state of a ticket.
String representing the object's type. Always has the value ticket_state.
The category of the ticket state
The state the ticket is currently in, in a human readable form - visible in Intercom
The state the ticket is currently in, in a human readable form - visible to customers, in the messenger, email and tickets portal.
{ "type": "ticket_state", "id": "12", "category": "in_progress", "internal_label": "With Dev Team", "external_label": "In Progress", "archived": false, "ticket_types": { "type": "list", "data": [ … ] } }
A ticket type, used to define the data fields to be captured in a ticket.
String representing the object's type. Always has the value ticket_type.
A list of attributes associated with a given ticket type.
{ "type": "ticket_type", "id": "1295", "category": "Customer", "name": "Bug", "description": "A bug that has been reported.", "icon": "🐞", "workspace_id": "ecahpwf5", "ticket_type_attributes": { "type": "string", "ticket_type_attributes": [ … ] }, "ticket_states": { "type": "list", "data": [ … ] }, "archived": false, "created_at": 0, "updated_at": 0 }
Payload of the request to reply on behalf of a contact using their intercom_user_id
The time the reply was created. If not provided, the current time will be used.
A list of image URLs that will be added as attachments. You can include up to 10 URLs.
curl -i -X POST \ 'https://api.intercom.io/tickets/{id}/reply' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "message_type": "comment", "type": "user", "intercom_user_id": "66fd02b89ffbe52cc8b3ab2a", "body": "Thanks again :)" }'
{ "type": "ticket_part", "id": "92", "part_type": "note", "body": "<h2>An Unordered HTML List</h2>\n<ul>\n<li>Coffee</li>\n<li>Tea</li>\n<li>Milk</li>\n</ul>\n<h2>An Ordered HTML List</h2>\n<ol>\n<li>Coffee</li>\n<li>Tea</li>\n<li>Milk</li>\n</ol>", "created_at": 1727857342, "updated_at": 1727857342, "author": { "id": "991267306", "type": "admin", "name": "Ciaran412 Lee", "email": "admin412@email.com" }, "attachments": [], "redacted": false }
curl -i -X POST \ 'https://api.intercom.io/tickets/{ticket_id}/tags' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "id": 88, "admin_id": 991267321 }'
{ "type": "tag", "id": "88", "name": "Manual tag" }
curl -i -X DELETE \ 'https://api.intercom.io/tickets/{ticket_id}/tags/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "admin_id": 991267336 }'
{ "type": "tag", "id": "91", "name": "Manual tag" }
The list of contacts (users or leads) affected by this ticket. Currently only one is allowed
The ID of the company that the ticket is associated with. The unique identifier for the company which is given by Intercom
The time the ticket was created. If not provided, the current time will be used.
The attributes set on the ticket. When setting the default title and description attributes, the attribute keys that should be used are _default_title_ and _default_description_. When setting ticket type attributes of the list attribute type, the key should be the attribute name and the value of the attribute should be the list item id, obtainable by listing the ticket type. For example, if the ticket type has an attribute called priority of type list, the key should be priority and the value of the attribute should be the guid of the list item (e.g. de1825a0-0164-4070-8ca6-13e22462fa7e).
curl -i -X POST \ https://api.intercom.io/tickets \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "ticket_type_id": 84, "contacts": [ { "id": "66fd02f79ffbe52cc8b3ab35" } ], "ticket_attributes": { "_default_title_": "example", "_default_description_": "there is a problem" } }'
Successful response
The ID of the Ticket used in the Intercom Inbox and Messenger. Do not use ticket_id for API queries.
An object containing the different attributes associated to the ticket as key-value pairs. For the default title and description attributes, the keys are _default_title_ and _default_description_.
A ticket type, used to define the data fields to be captured in a ticket.
The time the ticket was created as a UTC Unix timestamp.
The last time the ticket was updated as a UTC Unix timestamp.
The time the ticket will be snoozed until as a UTC Unix timestamp. If null, the ticket is not currently snoozed.
An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.
A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts.
{ "type": "ticket", "id": "325", "ticket_id": "31", "ticket_attributes": { "_default_title_": "example", "_default_description_": "there is a problem" }, "ticket_state": { "type": "ticket_state", "id": "5625", "category": "submitted", "internal_label": "Submitted", "external_label": "Submitted" }, "ticket_type": { "type": "ticket_type", "id": "84", "name": "my-ticket-type-23", "description": "my ticket type description is awesome.", "icon": "🦁", "workspace_id": "this_is_an_id688_that_should_be_at_least_", "archived": false, "created_at": 1727857399, "updated_at": 1727857399, "is_internal": false, "ticket_type_attributes": { … }, "category": "Back-office" }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "admin_assignee_id": "0", "team_assignee_id": "0", "created_at": 1727857400, "updated_at": 1727857401, "ticket_parts": { "type": "ticket_part.list", "ticket_parts": [ … ], "total_count": 1 }, "open": true, "linked_objects": { "type": "list", "data": [], "total_count": 0, "has_more": false }, "category": "Back-office", "is_shared": false }
The attributes set on the ticket.
Specify if a ticket is open. Set to false to close a ticket. Closing a ticket will also unsnooze it.
curl -i -X PUT \ 'https://api.intercom.io/tickets/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "ticket_attributes": { "_default_title_": "example", "_default_description_": "there is a problem" }, "assignment": { "admin_id": "991267374", "assignee_id": "991267376" }, "open": true, "snoozed_until": 1673609604, "ticket_state_id": 5642 }'
Successful response
The ID of the Ticket used in the Intercom Inbox and Messenger. Do not use ticket_id for API queries.
An object containing the different attributes associated to the ticket as key-value pairs. For the default title and description attributes, the keys are _default_title_ and _default_description_.
A ticket type, used to define the data fields to be captured in a ticket.
The time the ticket was created as a UTC Unix timestamp.
The last time the ticket was updated as a UTC Unix timestamp.
The time the ticket will be snoozed until as a UTC Unix timestamp. If null, the ticket is not currently snoozed.
An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.
A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts.
{ "type": "ticket", "id": "326", "ticket_id": "32", "ticket_attributes": { "_default_title_": "example", "_default_description_": "there is a problem" }, "ticket_state": { "type": "ticket_state", "id": "5642", "category": "in_progress", "internal_label": "In progress", "external_label": "In progress" }, "ticket_type": { "type": "ticket_type", "id": "86", "name": "my-ticket-type-25", "description": "my ticket type description is awesome.", "icon": "🦁", "workspace_id": "this_is_an_id692_that_should_be_at_least_", "archived": false, "created_at": 1727857403, "updated_at": 1727857403, "is_internal": false, "ticket_type_attributes": { … }, "category": "Back-office" }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "admin_assignee_id": "991267376", "team_assignee_id": "0", "created_at": 1727857404, "updated_at": 1727857410, "ticket_parts": { "type": "ticket_part.list", "ticket_parts": [ … ], "total_count": 6 }, "open": true, "snoozed_until": 1727971200, "linked_objects": { "type": "list", "data": [], "total_count": 0, "has_more": false }, "category": "Back-office", "is_shared": false }
curl -i -X GET \ 'https://api.intercom.io/tickets/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
Ticket found
The ID of the Ticket used in the Intercom Inbox and Messenger. Do not use ticket_id for API queries.
An object containing the different attributes associated to the ticket as key-value pairs. For the default title and description attributes, the keys are _default_title_ and _default_description_.
A ticket type, used to define the data fields to be captured in a ticket.
The time the ticket was created as a UTC Unix timestamp.
The last time the ticket was updated as a UTC Unix timestamp.
The time the ticket will be snoozed until as a UTC Unix timestamp. If null, the ticket is not currently snoozed.
An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.
A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts.
{ "type": "ticket", "id": "330", "ticket_id": "36", "ticket_attributes": { "_default_title_": "attribute_value", "_default_description_": null }, "ticket_state": { "type": "ticket_state", "id": "5681", "category": "submitted", "internal_label": "Submitted", "external_label": "Submitted" }, "ticket_type": { "type": "ticket_type", "id": "91", "name": "my-ticket-type-30", "description": "my ticket type description is awesome.", "icon": "🦁", "workspace_id": "this_is_an_id702_that_should_be_at_least_", "archived": false, "created_at": 1727857428, "updated_at": 1727857428, "is_internal": false, "ticket_type_attributes": { … }, "category": "Back-office" }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "admin_assignee_id": "0", "team_assignee_id": "0", "created_at": 1727857429, "updated_at": 1727857431, "ticket_parts": { "type": "ticket_part.list", "ticket_parts": [ … ], "total_count": 1 }, "open": true, "linked_objects": { "type": "list", "data": [], "total_count": 0, "has_more": false }, "category": "Back-office", "is_shared": false }
curl -i -X DELETE \ 'https://api.intercom.io/tickets/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "id": "331", "object": "ticket", "deleted": true }
You can search for multiple tickets by the value of their attributes in order to fetch exactly which ones you want.
To search for tickets, you send a POST request to https://api.intercom.io/tickets/search.
This will accept a query object in the body which will define your filters.
Search queries can be complex, so optimizing them can help the performance of your search. Use the AND and OR operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is 20 results per page. See the pagination section for more details on how to use the starting_after param.
You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiples there can be:
Most keys listed as part of the Ticket model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as created_at accepts a date, the value cannot be a string such as "foobar").
| Field | Type |
|---|---|
| id | String |
| created_at | Date (UNIX timestamp) |
| updated_at | Date (UNIX timestamp) |
| default_title | String |
| default_description | String |
| category | String |
| ticket_type_id | String |
| contact_ids | String |
| teammate_ids | String |
| admin_assignee_id | String |
| team_assignee_id | String |
| open | Boolean |
| state | String |
| snoozed_until | Date (UNIX timestamp) |
| ticket_attribute.{id} | String or Boolean or Date (UNIX timestamp) or Float or Integer |
You may use the <= or >= operators to search by created_at.
The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string ("="). The operator has to be compatible with the field's type (eg. you cannot search with > for a given string value as it's only compatible for integer's and dates).
| Operator | Valid Types | Description |
|---|---|---|
| = | All | Equals |
| != | All | Doesn't Equal |
| IN | All | In Shortcut for OR queries Values most be in Array |
| NIN | All | Not In Shortcut for OR ! queries Values must be in Array |
| > | Integer Date (UNIX Timestamp) | Greater (or equal) than |
| < | Integer Date (UNIX Timestamp) | Lower (or equal) than |
| ~ | String | Contains |
| !~ | String | Doesn't Contain |
| ^ | String | Starts With |
| $ | String | Ends With |
Search using Intercoms Search APIs with a single filter.
The accepted operators you can use to define how you want to search for the value.
curl -i -X POST \ https://api.intercom.io/tickets/search \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "query": { "operator": "AND", "value": [ { "field": "created_at", "operator": ">", "value": "1306054154" } ] }, "pagination": { "per_page": 5 } }'
{ "type": "ticket.list", "pages": { "type": "pages", "page": 1, "per_page": 5, "total_pages": 1 }, "total_count": 1, "tickets": [ { … } ] }