Skip to content
Home/
REST API Reference
/
/
Retrieve a ticket

Intercom API (Unstable)

The intercom API reference.

Download OpenAPI description
api.intercom.io.json
api.intercom.io.yaml
Overview
URL
https://developers.intercom.com
License
MIT
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

SchemasOperations

AI Content

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.",

SchemasOperations

Articles

Everything about your Articles

SchemasOperations

Away Status Reasons

Everything about your Away Status Reasons

Operations

Brands

Everything about your Brands

SchemasOperations

Calls

Everything about your Calls

SchemasOperations

Companies

Everything about your Companies

SchemasOperations

Contacts

Everything about your contacts

SchemasOperations

Conversations

Everything about your Conversations

SchemasOperations

Custom Channel Events

With the "Custom Channel" integration, you can bring Fin and Intercom capabilities to your own platform via API, enabling powerful custom integrations.

Intercom treats your integration like any other Intercom channel, allowing your application and Intercom to exchange events seamlessly. This makes it possible, for example, for your users to interact with Fin directly within your own application’s UI.

Note: "Fin over API" is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support.

Operations

Custom Object Instances

Everything about your Custom Object instances.

Permission Requirements

From now on, to access this endpoint, you need additional permissions. Please head over to the Developer Hub app package authentication settings to configure the required permissions.

SchemasOperations

Data Attributes

Everything about your Data Attributes

SchemasOperations

Data Connectors

Everything about your Data Connectors

SchemasOperations

Data Events

Everything about your Data Events

SchemasOperations

Data Export

Everything about your Data Exports

SchemasOperations

Emails

Everything about your Emails

SchemasOperations

Fin Agent

Access Fin programmatically via the Fin Agent API endpoints.

 

Managed Availability

The Fin Agent API is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support.

 

Integration is centered around two endpoints (/fin/start and /fin/reply) and a set of webhook events that notify your application of Fin's status and responses.

 

Webhook Events

Configure a webhook endpoint in the Fin Agent API settings to receive events. See the setup guide for configuration details.

  • fin_status_updated - Fired when Fin's status changes (escalated, resolved, complete)
  • fin_replied - Fired when Fin sends a reply to the user

All webhook requests include an X-Fin-Agent-API-Webhook-Signature header for request validation.

Schemas

Help Center

Everything about your Help Center

SchemasOperations

Internal Articles

Everything about your Internal Articles

SchemasOperations

Jobs

Everything about jobs

SchemasOperations

Macros

Operations related to saved replies (macros) in conversations

SchemasOperations

Messages

Everything about your messages

SchemasOperations

News

Everything about your News

SchemasOperations

Notes

Everything about your Notes

SchemasOperations

Segments

Everything about your Segments

SchemasOperations

Subscription Types

Everything about subscription types

SchemasOperations

Switch

Everything about Switch

Operations

Tags

Everything about tags

SchemasOperations

Teams

Everything about your Teams

SchemasOperations

Ticket States

Everything about your ticket states

Operations

Ticket Type Attributes

Everything about your ticket type attributes

Operations

Ticket Types

Everything about your ticket types

Operations

Tickets

Everything about your tickets

SchemasOperations

Update a ticket

Request

You can update a ticket.

Security
bearerAuth
Path
idstringrequired

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

Not the Inbox ticket ID

This is the internal id field from the API response, not the ticket_id displayed in the Intercom Inbox (e.g., #12345). Use the id value from the ticket object returned by the API.

Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default Unstable
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: Unstable
Bodyapplication/json
skip_notificationsboolean

Option to disable notifications when a Ticket is updated.

Example: true
ticket_attributesobject

The attributes set on the ticket.

Example: {"_default_title_":"example","_default_description_":"having a problem"}
ticket_state_idstring

The ID of the ticket state associated with the ticket type.

Example: "123"
company_idstring

The ID of the company that the ticket is associated with. The unique identifier for the company which is given by Intercom. Set to nil to remove company.

Example: "5f4d3c1c-7b1b-4d7d-a97e-6095715c6632"
openboolean

Specify if a ticket is open. Set to false to close a ticket. Closing a ticket will also unsnooze it.

Example: true
is_sharedboolean

Specify whether the ticket is visible to users.

Example: true
snoozed_untilinteger(timestamp)

The time you want the ticket to reopen.

Example: 1673609604
admin_idinteger

The ID of the admin performing ticket update. Needed for workflows execution and attributing actions to specific admins.

Example: 123
assignee_idstring

The ID of the admin or team to which the ticket is assigned. Set this 0 to unassign it.

Example: "123"
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"
    },
    "admin_id": 991268011,
    "assignee_id": 991268013,
    "open": true,
    "snoozed_until": 1673609604,
    "ticket_state_id": 8498
  }'

Responses

Successful response

Bodyapplication/json
typestring

Always ticket

Default "ticket"
Value"ticket"
Example: "ticket"
idstring

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

Example: "1295"
ticket_idstring

The ID of the Ticket used in the Intercom Inbox and Messenger. Do not use ticket_id for API queries.

Example: "1390"
categorystring

Category of the Ticket.

Enum"Customer""Back-office""Tracker"
Example: "Customer"
ticket_attributesobject(Ticket Attributes)

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

Example: {"_default_title_":"Found a bug","_default_description_":"The button's not working"}
ticket_stateobject or null(Ticket State)

A ticket state, used to define the state of a ticket.

ticket_typeobject or null(Ticket Type)

A ticket type, used to define the data fields to be captured in a ticket.

contactsobject(Contacts)

The list of contacts affected by a ticket.

admin_assignee_idstring

The id representing the admin assigned to the ticket.

Example: "1295"
team_assignee_idstring

The id representing the team assigned to the ticket.

Example: "1295"
created_atinteger(date-time)

The time the ticket was created as a UTC Unix timestamp.

Example: 1663597223
updated_atinteger(date-time)

The last time the ticket was updated as a UTC Unix timestamp.

Example: 1663597260
openboolean

Whether or not the ticket is open. If false, the ticket is closed.

Example: true
snoozed_untilinteger(date-time)

The time the ticket will be snoozed until as a UTC Unix timestamp. If null, the ticket is not currently snoozed.

Example: 1663597260
linked_objectsobject(Linked Objects)

An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.

ticket_partsobject(Ticket Parts)

A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts.

is_sharedboolean

Whether or not the ticket is shared with the customer.

Example: true
previous_ticket_state_idstring or null

The ID of the previous ticket state from the most recent state change. Returns null if no state change history exists. Useful for tracking state transitions for reporting and compliance.

Example: "7493"
Response
application/json
{
  "type": "ticket",
  "id": "627",
  "ticket_id": "34",
  "ticket_attributes": {
    "_default_title_": "example",
    "_default_description_": "there is a problem"
  },
  "ticket_state": {
    "type": "ticket_state",
    "id": "8498",
    "category": "in_progress",
    "internal_label": "In progress",
    "external_label": "In progress"
  },
  "ticket_type": {
    "type": "ticket_type",
    "id": "90",
    "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": 1734537948,
    "updated_at": 1734537948,
    "is_internal": false,
    "ticket_type_attributes": { … },
    "category": "Back-office"
  },
  "contacts": {
    "type": "contact.list",
    "contacts": [ … ]
  },
  "admin_assignee_id": "991268013",
  "team_assignee_id": "0",
  "created_at": 1734537950,
  "updated_at": 1734537955,
  "ticket_parts": {
    "type": "ticket_part.list",
    "ticket_parts": [ … ],
    "total_count": 6
  },
  "open": true,
  "snoozed_until": 1734627600,
  "linked_objects": {
    "type": "list",
    "data": [],
    "total_count": 0,
    "has_more": false
  },
  "category": "Back-office",
  "is_shared": false
}

Retrieve a ticket

Request

You can fetch the details of a single ticket.

Security
bearerAuth
Path
idstringrequired

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

Not the Inbox ticket ID

This is the internal id field from the API response, not the ticket_id displayed in the Intercom Inbox (e.g., #12345). Use the id value from the ticket object returned by the API.

Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default Unstable
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: Unstable
curl -i -X GET \
  'https://api.intercom.io/tickets/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: Unstable'

Responses

Ticket found

Bodyapplication/json
typestring

Always ticket

Default "ticket"
Value"ticket"
Example: "ticket"
idstring

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

Example: "1295"
ticket_idstring

The ID of the Ticket used in the Intercom Inbox and Messenger. Do not use ticket_id for API queries.

Example: "1390"
categorystring

Category of the Ticket.

Enum"Customer""Back-office""Tracker"
Example: "Customer"
ticket_attributesobject(Ticket Attributes)

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

Example: {"_default_title_":"Found a bug","_default_description_":"The button's not working"}
ticket_stateobject or null(Ticket State)

A ticket state, used to define the state of a ticket.

ticket_typeobject or null(Ticket Type)

A ticket type, used to define the data fields to be captured in a ticket.

contactsobject(Contacts)

The list of contacts affected by a ticket.

admin_assignee_idstring

The id representing the admin assigned to the ticket.

Example: "1295"
team_assignee_idstring

The id representing the team assigned to the ticket.

Example: "1295"
created_atinteger(date-time)

The time the ticket was created as a UTC Unix timestamp.

Example: 1663597223
updated_atinteger(date-time)

The last time the ticket was updated as a UTC Unix timestamp.

Example: 1663597260
openboolean

Whether or not the ticket is open. If false, the ticket is closed.

Example: true
snoozed_untilinteger(date-time)

The time the ticket will be snoozed until as a UTC Unix timestamp. If null, the ticket is not currently snoozed.

Example: 1663597260
linked_objectsobject(Linked Objects)

An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.

ticket_partsobject(Ticket Parts)

A list of Ticket Part objects for each note and event in the ticket. There is a limit of 500 parts.

is_sharedboolean

Whether or not the ticket is shared with the customer.

Example: true
previous_ticket_state_idstring or null

The ID of the previous ticket state from the most recent state change. Returns null if no state change history exists. Useful for tracking state transitions for reporting and compliance.

Example: "7493"
Response
application/json
{
  "type": "ticket",
  "id": "631",
  "ticket_id": "38",
  "ticket_attributes": {
    "_default_title_": "attribute_value",
    "_default_description_": null
  },
  "ticket_state": {
    "type": "ticket_state",
    "id": "8537",
    "category": "submitted",
    "internal_label": "Submitted",
    "external_label": "Submitted"
  },
  "ticket_type": {
    "type": "ticket_type",
    "id": "95",
    "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": 1734537973,
    "updated_at": 1734537973,
    "is_internal": false,
    "ticket_type_attributes": { … },
    "category": "Back-office"
  },
  "contacts": {
    "type": "contact.list",
    "contacts": [ … ]
  },
  "admin_assignee_id": "0",
  "team_assignee_id": "0",
  "created_at": 1734537974,
  "updated_at": 1734537976,
  "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
}

Delete a ticket

Request

Irreversible operation

Deleting a ticket is permanent and cannot be reversed.

Deleting a ticket permanently removes it from the inbox. All sensitive data is deleted, including admin and user replies, ticket attributes, uploads, and related content. The ticket will still appear in reporting, though some data may be incomplete due to the deletion.

Security
bearerAuth
Path
idstringrequired

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

Not the Inbox ticket ID

This is the internal id field from the API response, not the ticket_id displayed in the Intercom Inbox (e.g., #12345). Use the id value from the ticket object returned by the API.

Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default Unstable
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: Unstable
curl -i -X DELETE \
  'https://api.intercom.io/tickets/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: Unstable'

Responses

successful

Bodyapplication/json
idstring

The unique identifier for the ticket.

Example: "5ba682d23d7cf92bef87bfd4"
objectstring

always ticket

Value"ticket"
Example: "ticket"
deletedboolean

Whether the ticket is deleted or not.

Example: true
Response
application/json
{
  "id": "632",
  "object": "ticket",
  "deleted": true
}

Visitors

Everything about your Visitors

Operations

Workflows

Export workflow configurations from your workspace.

Operations

Models

Schemas

Export

Operations

Folders

SchemasOperations

WhatsApp

Operations