The intercom API reference.
URL https://developers.intercom.com
License MIT
The intercom API reference.
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_.
The state the ticket is currently in
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.
The state the ticket is currently in, in a human readable form - visible in Intercom
{ "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": "submitted", "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": { … }, "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, "ticket_state_internal_label": "string", "ticket_state_external_label": "string" }
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 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": [ … ] }, "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.
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: 2.11' \ -d '{ "message_type": "comment", "type": "user", "intercom_user_id": "667d619d8a68186f43bafe82", "body": "Thanks again :)" }'
{ "type": "ticket_part", "id": "122", "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": 1719493024, "updated_at": 1719493024, "author": { "id": "991267829", "type": "admin", "name": "Ciaran375 Lee", "email": "admin375@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: 2.11' \ -d '{ "id": 134, "admin_id": 991267844 }'
{ "type": "tag", "id": "134", "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: 2.11' \ -d '{ "admin_id": 991267853 }'
{ "type": "tag", "id": "137", "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 ID that you set upon company creation.
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: 2.11' \ -d '{ "ticket_type_id": 106, "contacts": [ { "id": "667d61b78a68186f43bafe8d" } ], "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_.
The state the ticket is currently in
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.
The state the ticket is currently in, in a human readable form - visible in Intercom
{ "type": "ticket", "id": "489", "ticket_id": "48", "ticket_attributes": { "_default_title_": "example", "_default_description_": "there is a problem" }, "ticket_state": "submitted", "ticket_type": { "type": "ticket_type", "id": "106", "name": "my-ticket-type-15", "description": "my ticket type description is awesome.", "icon": "🦁", "workspace_id": "this_is_an_id648_that_should_be_at_least_", "archived": false, "created_at": 1719493047, "updated_at": 1719493047, "is_internal": false, "ticket_type_attributes": { … }, "category": "Back-office" }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "admin_assignee_id": "0", "team_assignee_id": "0", "created_at": 1719493048, "updated_at": 1719493048, "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, "ticket_state_internal_label": "Submitted", "ticket_state_external_label": "Submitted" }
The attributes set on the ticket.
The state of 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: 2.11' \ -d '{ "ticket_attributes": { "_default_title_": "example", "_default_description_": "there is a problem" }, "state": "in_progress", "assignment": { "admin_id": "991267883", "assignee_id": "991267885" }, "open": true, "snoozed_until": 1673609604 }'
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_.
The state the ticket is currently in
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.
The state the ticket is currently in, in a human readable form - visible in Intercom
{ "type": "ticket", "id": "490", "ticket_id": "49", "ticket_attributes": { "_default_title_": "example", "_default_description_": "there is a problem" }, "ticket_state": "in_progress", "ticket_type": { "type": "ticket_type", "id": "108", "name": "my-ticket-type-17", "description": "my ticket type description is awesome.", "icon": "🦁", "workspace_id": "this_is_an_id652_that_should_be_at_least_", "archived": false, "created_at": 1719493050, "updated_at": 1719493050, "is_internal": false, "ticket_type_attributes": { … }, "category": "Back-office" }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "admin_assignee_id": "991267885", "team_assignee_id": "0", "created_at": 1719493051, "updated_at": 1719493054, "ticket_parts": { "type": "ticket_part.list", "ticket_parts": [ … ], "total_count": 6 }, "open": true, "snoozed_until": 1719590400, "linked_objects": { "type": "list", "data": [], "total_count": 0, "has_more": false }, "category": "Back-office", "is_shared": false, "ticket_state_internal_label": "In progress", "ticket_state_external_label": "In progress" }
curl -i -X GET \ 'https://api.intercom.io/tickets/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: 2.11'
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_.
The state the ticket is currently in
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.
The state the ticket is currently in, in a human readable form - visible in Intercom
{ "type": "ticket", "id": "493", "ticket_id": "52", "ticket_attributes": { "_default_title_": "attribute_value", "_default_description_": null }, "ticket_state": "submitted", "ticket_type": { "type": "ticket_type", "id": "112", "name": "my-ticket-type-21", "description": "my ticket type description is awesome.", "icon": "🦁", "workspace_id": "this_is_an_id660_that_should_be_at_least_", "archived": false, "created_at": 1719493060, "updated_at": 1719493060, "is_internal": false, "ticket_type_attributes": { … }, "category": "Back-office" }, "contacts": { "type": "contact.list", "contacts": [ … ] }, "admin_assignee_id": "0", "team_assignee_id": "0", "created_at": 1719493061, "updated_at": 1719493061, "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, "ticket_state_internal_label": "Submitted", "ticket_state_external_label": "Submitted" }
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) |
| title | String |
| 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: 2.11' \ -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": [ { … } ] }