Skip to content
Home/
REST API Reference
/
/
Retrieve an execution res...

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 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 Connector

A data connector allows you to make HTTP requests to external APIs from Intercom workflows and AI agents.

typestring

The type of object - data_connector.

Value"data_connector"
Example: "data_connector"
idstring

The unique identifier for the data connector.

Example: "12345"
namestring

The name of the data connector.

Example: "Slack Notification Service"
descriptionstring or null

A description of what this data connector does.

Example: "Posts conversation updates to Slack channel"
statestring

The current state of the data connector.

Enum"draft""live"
Example: "live"
http_methodstring

The HTTP method used by the data connector.

Enum"get""post""put""delete""patch"
Example: "post"
usagestring

Where this data connector can be used.

Enum"workflow_and_inbox""fin""fin_voice"
Example: "workflow_and_inbox"
created_atstring(date-time)

The time the data connector was created.

Example: "2025-11-15T09:30:00Z"
updated_atstring(date-time)

The time the data connector was last updated.

Example: "2026-01-20T14:22:15Z"
execution_results_urlstring

The URL path to fetch execution results for this connector.

Example: "/data_connectors/12345/execution_results"
{
  "type": "data_connector",
  "id": "12345",
  "name": "Slack Notification Service",
  "description": "Posts conversation updates to Slack channel",
  "state": "live",
  "http_method": "post",
  "usage": "workflow_and_inbox",
  "created_at": "2025-11-15T09:30:00Z",
  "updated_at": "2026-01-20T14:22:15Z",
  "execution_results_url": "/data_connectors/12345/execution_results"
}

Data Connector Execution Result

An execution result from a data connector HTTP request.

typestring

The type of object - data_connector.execution.

Value"data_connector.execution"
Example: "data_connector.execution"
idstring

The unique identifier for the execution result.

Example: "99001"
data_connector_idstring

The unique identifier of the data connector that produced this result.

Example: "12345"
successboolean

Whether the execution was successful.

Example: true
http_statusinteger or null

The HTTP status code returned by the external API.

Example: 200
http_methodstring

The HTTP method used for the request.

Enum"get""post""put""delete""patch"
Example: "post"
error_typestring or null

The type of error that occurred, if any.

Enum"request_configuration_error""faraday_error""3rd_party_error""response_mapping_error""token_refresh_error""fin_action_response_formatting_error""fin_action_identity_verification_error""email_verification_error""non_fin_standalone_action_identity_verification_error""request_validation_error"
Example: "3rd_party_error"
error_messagestring or null

A human-readable error message. Query parameters, userinfo, and fragments in URLs are redacted.

Example: "Connection refused"
execution_time_msinteger or null

The execution time in milliseconds.

Example: 245
source_typestring or null

The type of source that triggered this execution.

Enum"custom_bot""inbound_custom_bot""button_custom_bot""answer""workflow""saved_reply""triggerable_custom_bot""inbox""fin"
Example: "workflow"
source_idstring or null

The identifier of the source that triggered this execution.

Example: "5001"
conversation_idstring or null

The conversation associated with this execution, if any.

Example: "8001"
created_atstring(date-time)

The time the execution occurred.

Example: "2026-02-10T18:15:32Z"
request_urlstring or null

The request URL. Query parameters, userinfo, and fragments are redacted.

Example: "https://api.example.com/webhook"
request_bodystring or null

The request body sent to the external API.

Example: "{\"message\": \"hello\"}"
response_bodystring or null

The response body from the external API.

Example: "{\"status\": \"ok\"}"
raw_response_bodystring or null

The raw (unmapped) response body.

Example: "{\"status\": \"ok\"}"
{
  "type": "data_connector.execution",
  "id": "99001",
  "data_connector_id": "12345",
  "success": true,
  "http_status": 200,
  "http_method": "post",
  "error_type": "3rd_party_error",
  "error_message": "Connection refused",
  "execution_time_ms": 245,
  "source_type": "workflow",
  "source_id": "5001",
  "conversation_id": "8001",
  "created_at": "2026-02-10T18:15:32Z",
  "request_url": "https://api.example.com/webhook",
  "request_body": "{\"message\": \"hello\"}",
  "response_body": "{\"status\": \"ok\"}",
  "raw_response_body": "{\"status\": \"ok\"}"
}

List all data connectors

Request

You can fetch a list of all data connectors for your workspace by making a GET request to https://api.intercom.io/data_connectors.

Data connectors allow you to make HTTP requests to external APIs from Intercom workflows and AI agents. Each connector in the response includes an execution_results_url for navigating to its execution logs.

Security
bearerAuth
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/data_connectors \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: Unstable'

Responses

successful

Bodyapplication/json
typestring

The type of object - list.

Value"list"
Example: "list"
dataArray of objects(Data Connector)

An array of data connector objects.

Response
application/json
{
  "type": "list",
  "data": [
    { … }
  ]
}

List execution results for a data connector

Request

Retrieve paginated execution logs for a specific data connector. Results from the last hour are returned by default. Use start_ts and end_ts to customize the time range.

Request/response bodies and request URL are excluded by default. Use include_bodies=true to include bodies. Use include_request_url=true to include the sanitised request URL.

Security
bearerAuth
Path
data_connector_idstringrequired

The unique identifier for the data connector.

Example: 12345
Query
per_pageinteger[ 1 .. 30 ]

The number of results per page (1-30, default 10).

Default 10
starting_afterstring

Cursor for pagination. Use the value from pages.next.starting_after in a previous response.

successstring

Filter by success status. Use true, false, or omit for all.

Enum"true""false"
error_typestring

Filter by error type.

Enum"request_configuration_error""faraday_error""3rd_party_error""response_mapping_error""token_refresh_error""fin_action_response_formatting_error""fin_action_identity_verification_error""email_verification_error""non_fin_standalone_action_identity_verification_error""request_validation_error"
start_tsinteger

Unix timestamp for start of time range (default 1 hour ago).

end_tsinteger

Unix timestamp for end of time range (default now).

include_bodiesstring

Include request/response bodies in the response (default false).

Enum"true""false"
include_request_urlstring

Include the request URL in the response (default false).

Enum"true""false"
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/data_connectors/12345/execution_results?per_page=10&starting_after=string&success=true&error_type=request_configuration_error&start_ts=0&end_ts=0&include_bodies=true&include_request_url=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: Unstable'

Responses

successful

Bodyapplication/json
typestring

The type of object - list.

Value"list"
Example: "list"
dataArray of objects(Data Connector Execution Result)

An array of execution result objects.

pagesobject

Pagination information.

Response
application/json
{
  "type": "list",
  "data": [
    { … },
    { … }
  ],
  "pages": {
    "type": "pages",
    "per_page": 10,
    "next": { … }
  }
}

Retrieve an execution result

Request

Retrieve details for a specific data connector execution result. Always includes request/response bodies and the sanitised request URL.

Security
bearerAuth
Path
data_connector_idstringrequired

The unique identifier for the data connector.

Example: 12345
idstringrequired

The unique identifier for the execution result.

Example: 99001
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/data_connectors/12345/execution_results/99001 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: Unstable'

Responses

successful

Bodyapplication/json
typestring

The type of object - data_connector.execution.

Value"data_connector.execution"
Example: "data_connector.execution"
idstring

The unique identifier for the execution result.

Example: "99001"
data_connector_idstring

The unique identifier of the data connector that produced this result.

Example: "12345"
successboolean

Whether the execution was successful.

Example: true
http_statusinteger or null

The HTTP status code returned by the external API.

Example: 200
http_methodstring

The HTTP method used for the request.

Enum"get""post""put""delete""patch"
Example: "post"
error_typestring or null

The type of error that occurred, if any.

Enum"request_configuration_error""faraday_error""3rd_party_error""response_mapping_error""token_refresh_error""fin_action_response_formatting_error""fin_action_identity_verification_error""email_verification_error""non_fin_standalone_action_identity_verification_error""request_validation_error"
Example: "3rd_party_error"
error_messagestring or null

A human-readable error message. Query parameters, userinfo, and fragments in URLs are redacted.

Example: "Connection refused"
execution_time_msinteger or null

The execution time in milliseconds.

Example: 245
source_typestring or null

The type of source that triggered this execution.

Enum"custom_bot""inbound_custom_bot""button_custom_bot""answer""workflow""saved_reply""triggerable_custom_bot""inbox""fin"
Example: "workflow"
source_idstring or null

The identifier of the source that triggered this execution.

Example: "5001"
conversation_idstring or null

The conversation associated with this execution, if any.

Example: "8001"
created_atstring(date-time)

The time the execution occurred.

Example: "2026-02-10T18:15:32Z"
request_urlstring or null

The request URL. Query parameters, userinfo, and fragments are redacted.

Example: "https://api.example.com/webhook"
request_bodystring or null

The request body sent to the external API.

Example: "{\"message\": \"hello\"}"
response_bodystring or null

The response body from the external API.

Example: "{\"status\": \"ok\"}"
raw_response_bodystring or null

The raw (unmapped) response body.

Example: "{\"status\": \"ok\"}"
Response
application/json
{
  "type": "data_connector.execution",
  "id": "99001",
  "data_connector_id": "12345",
  "success": true,
  "http_status": 200,
  "http_method": "post",
  "execution_time_ms": 150,
  "source_type": "workflow",
  "source_id": "5001",
  "conversation_id": "8001",
  "created_at": "2026-02-10T18:15:32Z",
  "request_url": "https://api.example.com/webhook",
  "request_body": "{\"channel\": \"#alerts\", \"text\": \"Conversation updated\"}",
  "response_body": "{\"ok\": true}",
  "raw_response_body": "{\"ok\": true}"
}

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

Emails

Everything about your Emails

SchemasOperations

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

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

Workflows

Export workflow configurations from your workspace.

Operations

Models

Schemas

Custom Channel Events

Operations

WhatsApp

Operations