Skip to content
Home/
REST API Reference
/
/
Start a conversation with...

Intercom API (2.14)

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

Calls

Everything about Calls

SchemasOperations

Companies

Everything about your Companies

SchemasOperations

Contacts

Everything about your contacts

SchemasOperations

Conversations

Everything about your Conversations

SchemasOperations

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 Events

Everything about your Data Events

SchemasOperations

Data Export

Everything about your Data Exports

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

Fin Agent Message

A message exchanged within a Fin Agent conversation.

authorstringrequired

The author that created the message.

Enum"user""agent""fin"
Example: "user"
bodystringrequired

The body of the message. Accepts both plain text and HTML format. When sending a message to Fin, this should contain the user's message. Fin's response will be returned as HTML.

Example: "How can I see my account details?"
timestampstring(date-time)required

The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision.

Example: "2025-01-24T10:01:20.000Z"
timestamp_msstring(date-time)

The timestamp when the message was created, with millisecond precision. Only present in webhook event responses (fin_replied).

Example: "2025-01-24T10:01:20.456Z"
{
  "author": "user",
  "body": "How can I see my account details?",
  "timestamp": "2025-01-24T10:01:20.000Z",
  "timestamp_ms": "2025-01-24T10:01:20.456Z"
}

Fin Agent User

A user object representing the user in a Fin Agent conversation.

idstringrequired

The ID of the user. This value will be used to uniquely identify the user during a conversation with Fin. Maps to the user_id field on the Intercom User object.

Example: "123456"
namestring

The name of the user.

Example: "John Doe"
emailstring(email)

The email of the user.

Example: "john.doe@example.com"
attributesobject

A hash of attributes associated with the user. Attributes can be used by Fin to target content and responses. Limit to 10 attributes.

Example: {"plan_type":"Pro","subscription_status":"active"}
{
  "id": "123456",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "attributes": {
    "plan_type": "Pro",
    "subscription_status": "active"
  }
}

Fin Agent Attachment

An attachment object representing a file or URL attachment included with a message. Attachments can be used to provide additional context to Fin. Maximum of 10 attachments per request.

typestringrequired

The type of attachment.

Enum"url""file"
Example: "url"
urlstring(uri)

The URL of the attachment. Required when type is 'url'. Must be publicly accessible.

Example: "https://example.com/document.pdf"
namestring

The name of the file. Required when type is 'file'.

Example: "screenshot.png"
content_typestring

The MIME type of the file. Required when type is 'file'.

Example: "image/png"
datastring(byte)

Base64-encoded file data. Required when type is 'file'.

Example: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk..."
{
  "type": "url",
  "url": "https://example.com/document.pdf",
  "name": "screenshot.png",
  "content_type": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk..."
}

Fin Agent Conversation Metadata

Metadata about the conversation, including history and attributes.

historyArray of objects(Fin Agent Message)<= 10 items

An array of previous messages in the conversation before Fin is initialized. This data provides context to Fin and helps generate a better answer. Limit to the last 10 messages.

attributesobject

A hash of attributes associated with the conversation. These attributes can be used by Fin to provide more contextual responses. Limit to 10 attributes.

Example: {"priority_level":"high","department":"sales"}
{
  "history": [
    { … }
  ],
  "attributes": {
    "priority_level": "high",
    "department": "sales"
  }
}

Fin Agent Attribute Errors

Contains error details if any user or conversation attribute updates failed.

userobject

User-related attribute errors.

conversationobject

Conversation-related attribute errors.

{
  "user": {
    "attributes": { … }
  },
  "conversation": {
    "attributes": { … }
  }
}

Fin Agent Start Request

Request payload for initializing a Fin conversation.

conversation_idstringrequired

The ID of the conversation that is calling Fin via this API.

Example: "ext-123"
messageobject(Fin Agent Message)required

A message exchanged within a Fin Agent conversation.

message.​authorstringrequired

The author that created the message.

Enum"user""agent""fin"
Example: "user"
message.​bodystringrequired

The body of the message. Accepts both plain text and HTML format. When sending a message to Fin, this should contain the user's message. Fin's response will be returned as HTML.

Example: "How can I see my account details?"
message.​timestampstring(date-time)required

The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision.

Example: "2025-01-24T10:01:20.000Z"
message.​timestamp_msstring(date-time)

The timestamp when the message was created, with millisecond precision. Only present in webhook event responses (fin_replied).

Example: "2025-01-24T10:01:20.456Z"
userobject(Fin Agent User)required

A user object representing the user in a Fin Agent conversation.

user.​idstringrequired

The ID of the user. This value will be used to uniquely identify the user during a conversation with Fin. Maps to the user_id field on the Intercom User object.

Example: "123456"
user.​namestring

The name of the user.

Example: "John Doe"
user.​emailstring(email)

The email of the user.

Example: "john.doe@example.com"
user.​attributesobject

A hash of attributes associated with the user. Attributes can be used by Fin to target content and responses. Limit to 10 attributes.

Example: {"plan_type":"Pro","subscription_status":"active"}
attachmentsArray of objects(Fin Agent Attachment)<= 10 items

An array of attachments to include with the message. Maximum of 10 attachments.

conversation_metadataobject(Fin Agent Conversation Metadata)

Metadata about the conversation, including history and attributes.

{
  "conversation_id": "ext-123",
  "message": {
    "author": "user",
    "body": "How can I see my account details?",
    "timestamp": "2025-01-24T10:01:20.000Z",
    "timestamp_ms": "2025-01-24T10:01:20.456Z"
  },
  "user": {
    "id": "123456",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "attributes": { … }
  },
  "attachments": [
    { … }
  ],
  "conversation_metadata": {
    "history": [ … ],
    "attributes": { … }
  }
}

Fin Agent Reply Request

Request payload for sending a user reply to Fin.

conversation_idstringrequired

The ID of the conversation.

Example: "123456"
messageobject(Fin Agent Message)required

A message exchanged within a Fin Agent conversation.

message.​authorstringrequired

The author that created the message.

Enum"user""agent""fin"
Example: "user"
message.​bodystringrequired

The body of the message. Accepts both plain text and HTML format. When sending a message to Fin, this should contain the user's message. Fin's response will be returned as HTML.

Example: "How can I see my account details?"
message.​timestampstring(date-time)required

The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision.

Example: "2025-01-24T10:01:20.000Z"
message.​timestamp_msstring(date-time)

The timestamp when the message was created, with millisecond precision. Only present in webhook event responses (fin_replied).

Example: "2025-01-24T10:01:20.456Z"
userobject(Fin Agent User)required

A user object representing the user in a Fin Agent conversation.

user.​idstringrequired

The ID of the user. This value will be used to uniquely identify the user during a conversation with Fin. Maps to the user_id field on the Intercom User object.

Example: "123456"
user.​namestring

The name of the user.

Example: "John Doe"
user.​emailstring(email)

The email of the user.

Example: "john.doe@example.com"
user.​attributesobject

A hash of attributes associated with the user. Attributes can be used by Fin to target content and responses. Limit to 10 attributes.

Example: {"plan_type":"Pro","subscription_status":"active"}
attachmentsArray of objects(Fin Agent Attachment)<= 10 items

An array of attachments to include with the message. Maximum of 10 attachments.

{
  "conversation_id": "123456",
  "message": {
    "author": "user",
    "body": "How can I see my account details?",
    "timestamp": "2025-01-24T10:01:20.000Z",
    "timestamp_ms": "2025-01-24T10:01:20.456Z"
  },
  "user": {
    "id": "123456",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "attributes": { … }
  },
  "attachments": [
    { … }
  ]
}

Fin Agent Response

Response from the Fin Agent API endpoints.

conversation_idstring

The ID of the conversation.

Example: "ext-123"
user_idstring

The ID of the user.

Example: "user-456"
statusstring

Fin's current status in the conversation workflow.

  • thinking: Fin is currently thinking about a response
  • awaiting_user_reply: Fin is waiting for a user to reply
  • escalated: The conversation has been escalated
  • resolved: The user's query has been resolved
  • complete: Fin has completed its workflow
Enum"thinking""awaiting_user_reply""escalated""resolved""complete"
Example: "thinking"
created_at_msstring(date-time)

The timestamp the response was created at, with millisecond precision.

Example: "2025-01-24T10:00:00.123Z"
errorsobject(Fin Agent Attribute Errors)

Contains error details if any user or conversation attribute updates failed.

{
  "conversation_id": "ext-123",
  "user_id": "user-456",
  "status": "thinking",
  "created_at_ms": "2025-01-24T10:00:00.123Z",
  "errors": {
    "user": { … },
    "conversation": { … }
  }
}

Fin Agent Status Updated Event

Webhook event fired when Fin's status changes during a conversation. Fin will report its status to the client via this event.

event_namestringrequired

The name of the event.

Value"fin_status_updated"
Example: "fin_status_updated"
conversation_idstringrequired

The ID of the conversation.

Example: "123456"
user_idstringrequired

The ID of the user.

Example: "7891"
statusstringrequired

Fin's current status.

  • escalated: The conversation has been escalated to a human
  • resolved: The user's query has been resolved
  • complete: Fin has completed its workflow
Enum"escalated""resolved""complete"
Example: "escalated"
reasonstring

Optional. A human-readable explanation of why the conversation was escalated. Only present when status is 'escalated'. Possible values include:

  • "Escalation requested by user"
  • "Escalation rule: {rule_name}"
  • "Escalation rule matched"
  • "Routed to team"
  • "Conversation finished without resolution"
Example: "Escalation requested by user"
created_at_msstring(date-time)required

The timestamp the event was created at, with millisecond precision.

Example: "2025-01-24T10:00:00.123Z"
{
  "event_name": "fin_status_updated",
  "conversation_id": "123456",
  "user_id": "7891",
  "status": "escalated",
  "reason": "Escalation requested by user",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}

Fin Agent Replied Event

Webhook event fired when Fin replies to a user. The content of the response will be contained in the message object. Fin's status will update to 'awaiting_user_reply'.

event_namestringrequired

The name of the event.

Value"fin_replied"
Example: "fin_replied"
conversation_idstringrequired

The ID of the conversation.

Example: "123456"
user_idstringrequired

The ID of the user.

Example: "7891"
messageobjectrequired

Fin's answer to the user's query.

message.​authorstringrequired

The author of the message (always 'fin' for this event).

Value"fin"
Example: "fin"
message.​bodystringrequired

The HTML body of Fin's response.

Example: "<p>You can see your account details by clicking on the <em>Account</em> tab in the top right corner of the screen.</p>"
message.​timestamp_msstring(date-time)required

The timestamp the message was created at, with millisecond precision.

Example: "2025-01-24T09:01:00.456Z"
statusstringrequired

Fin's current status (always 'awaiting_user_reply' for this event).

Value"awaiting_user_reply"
Example: "awaiting_user_reply"
created_at_msstring(date-time)required

The timestamp the event was created at, with millisecond precision.

Example: "2025-01-24T10:00:00.123Z"
{
  "event_name": "fin_replied",
  "conversation_id": "123456",
  "user_id": "7891",
  "message": {
    "author": "fin",
    "body": "<p>You can see your account details by clicking on the <em>Account</em> tab in the top right corner of the screen.</p>",
    "timestamp_ms": "2025-01-24T09:01:00.456Z"
  },
  "status": "awaiting_user_reply",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}

Start a conversation with Fin

Request

Initialize Fin by passing it the user's message along with conversation history and user details.

These additional pieces of context will be used by Fin to provide a better and more contextual answer to the user.

Managed Availability

The Fin Agent API is currently under managed availability. Please reach out to your accounts team to discuss access.

Once Fin is initialized, it progresses through a series of statuses such as thinking, awaiting_user_reply, or resolved before ending with a status of complete.

During this workflow, the client should allow Fin to continue uninterrupted until a final complete status is returned via webhook, at which point control of the conversation passes back to the client.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

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

Default 2.14
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.14
Bodyapplication/jsonrequired
conversation_idstringrequired

The ID of the conversation that is calling Fin via this API.

Example: "ext-123"
messageobject(Fin Agent Message)required

A message exchanged within a Fin Agent conversation.

message.​authorstringrequired

The author that created the message.

Enum"user""agent""fin"
Example: "user"
message.​bodystringrequired

The body of the message. Accepts both plain text and HTML format. When sending a message to Fin, this should contain the user's message. Fin's response will be returned as HTML.

Example: "How can I see my account details?"
message.​timestampstring(date-time)required

The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision.

Example: "2025-01-24T10:01:20.000Z"
message.​timestamp_msstring(date-time)

The timestamp when the message was created, with millisecond precision. Only present in webhook event responses (fin_replied).

Example: "2025-01-24T10:01:20.456Z"
userobject(Fin Agent User)required

A user object representing the user in a Fin Agent conversation.

user.​idstringrequired

The ID of the user. This value will be used to uniquely identify the user during a conversation with Fin. Maps to the user_id field on the Intercom User object.

Example: "123456"
user.​namestring

The name of the user.

Example: "John Doe"
user.​emailstring(email)

The email of the user.

Example: "john.doe@example.com"
user.​attributesobject

A hash of attributes associated with the user. Attributes can be used by Fin to target content and responses. Limit to 10 attributes.

Example: {"plan_type":"Pro","subscription_status":"active"}
attachmentsArray of objects(Fin Agent Attachment)<= 10 items

An array of attachments to include with the message. Maximum of 10 attachments.

conversation_metadataobject(Fin Agent Conversation Metadata)

Metadata about the conversation, including history and attributes.

curl -i -X POST \
  https://api.intercom.io/fin/start \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.14' \
  -d '{
    "conversation_id": "ext-123",
    "message": {
      "author": "user",
      "body": "How can I see my account details?",
      "timestamp": "2025-01-24T10:01:20.000Z"
    },
    "user": {
      "id": "123456",
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }'

Responses

Fin conversation started successfully

Bodyapplication/json
conversation_idstring

The ID of the conversation.

Example: "ext-123"
user_idstring

The ID of the user.

Example: "user-456"
statusstring

Fin's current status in the conversation workflow.

  • thinking: Fin is currently thinking about a response
  • awaiting_user_reply: Fin is waiting for a user to reply
  • escalated: The conversation has been escalated
  • resolved: The user's query has been resolved
  • complete: Fin has completed its workflow
Enum"thinking""awaiting_user_reply""escalated""resolved""complete"
Example: "thinking"
created_at_msstring(date-time)

The timestamp the response was created at, with millisecond precision.

Example: "2025-01-24T10:00:00.123Z"
errorsobject(Fin Agent Attribute Errors)

Contains error details if any user or conversation attribute updates failed.

Response
application/json
{
  "conversation_id": "ext-123",
  "user_id": "user-456",
  "status": "thinking",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}

Reply to Fin

Request

Once Fin has returned a response to a user's message, its status will be awaiting_user_reply.

If a user replies, use this endpoint to send this response to Fin.

Managed Availability

The Fin Agent API is currently under managed availability. Please reach out to your accounts team to discuss access.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

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

Default 2.14
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.14
Bodyapplication/jsonrequired
conversation_idstringrequired

The ID of the conversation.

Example: "123456"
messageobject(Fin Agent Message)required

A message exchanged within a Fin Agent conversation.

message.​authorstringrequired

The author that created the message.

Enum"user""agent""fin"
Example: "user"
message.​bodystringrequired

The body of the message. Accepts both plain text and HTML format. When sending a message to Fin, this should contain the user's message. Fin's response will be returned as HTML.

Example: "How can I see my account details?"
message.​timestampstring(date-time)required

The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision.

Example: "2025-01-24T10:01:20.000Z"
message.​timestamp_msstring(date-time)

The timestamp when the message was created, with millisecond precision. Only present in webhook event responses (fin_replied).

Example: "2025-01-24T10:01:20.456Z"
userobject(Fin Agent User)required

A user object representing the user in a Fin Agent conversation.

user.​idstringrequired

The ID of the user. This value will be used to uniquely identify the user during a conversation with Fin. Maps to the user_id field on the Intercom User object.

Example: "123456"
user.​namestring

The name of the user.

Example: "John Doe"
user.​emailstring(email)

The email of the user.

Example: "john.doe@example.com"
user.​attributesobject

A hash of attributes associated with the user. Attributes can be used by Fin to target content and responses. Limit to 10 attributes.

Example: {"plan_type":"Pro","subscription_status":"active"}
attachmentsArray of objects(Fin Agent Attachment)<= 10 items

An array of attachments to include with the message. Maximum of 10 attachments.

curl -i -X POST \
  https://api.intercom.io/fin/reply \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.14' \
  -d '{
    "conversation_id": "123456",
    "message": {
      "author": "user",
      "body": "Here'\''s the information you requested.",
      "timestamp": "2025-01-24T09:01:00.000Z"
    },
    "user": {
      "id": "123456",
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }'

Responses

Reply sent successfully

Bodyapplication/json
conversation_idstring

The ID of the conversation.

Example: "ext-123"
user_idstring

The ID of the user.

Example: "user-456"
statusstring

Fin's current status in the conversation workflow.

  • thinking: Fin is currently thinking about a response
  • awaiting_user_reply: Fin is waiting for a user to reply
  • escalated: The conversation has been escalated
  • resolved: The user's query has been resolved
  • complete: Fin has completed its workflow
Enum"thinking""awaiting_user_reply""escalated""resolved""complete"
Example: "thinking"
created_at_msstring(date-time)

The timestamp the response was created at, with millisecond precision.

Example: "2025-01-24T10:00:00.123Z"
errorsobject(Fin Agent Attribute Errors)

Contains error details if any user or conversation attribute updates failed.

Response
application/json
{
  "conversation_id": "ext-123",
  "user_id": "user-456",
  "status": "thinking",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}

Help Center

Everything about your Help Center

SchemasOperations

Internal Articles

Everything about your Internal Articles

SchemasOperations

IP Allowlist

Manage IP allowlist settings to restrict workspace access to specific IP addresses or ranges.

Operations

Jobs

Everything about jobs

SchemasOperations

Messages

Everything about your messages

SchemasOperations

News

Everything about your News

SchemasOperations

Notes

Everything about your Notes

SchemasOperations

Reporting Data Export

Everything about Reporting Data Export. See this article for details on using the data to generate various metrics.

Operations

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

Visitors

Everything about your Visitors

Operations

Models

Schemas