Skip to content
Home/
REST API Reference
/
/
List all data connectors

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

Content Snippets

Everything about your Content Snippets

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 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: "Order Status Service"
descriptionstring or null

A description of what this data connector does.

Example: "Fetches order status from external fulfillment API"
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"
direct_fin_usageboolean

Whether this data connector is assigned to Fin for direct usage.

Example: false
created_by_admin_idstring

The ID of the admin who created this data connector.

Example: "12345"
updated_by_admin_idstring

The ID of the admin who last updated this data connector.

Example: "12345"
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": "Order Status Service",
  "description": "Fetches order status from external fulfillment API",
  "state": "live",
  "http_method": "post",
  "direct_fin_usage": false,
  "created_by_admin_id": "12345",
  "updated_by_admin_id": "12345",
  "created_at": "2025-11-15T09:30:00Z",
  "updated_at": "2026-01-20T14:22:15Z",
  "execution_results_url": "/data_connectors/12345/execution_results"
}

Data Connector (Detail)

Full detail view of a data connector, returned by GET /data_connectors/{id}. Includes configuration, data inputs, response fields, and object mappings.

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: "Order Status Service"
descriptionstring or null

A description of what this data connector does.

Example: "Fetches order status from external fulfillment API"
statestring

The current state of the data connector.

Enum"draft""live"
Example: "live"
urlstring or null

The URL of the external API endpoint. Supports template variables like {{order_id}}.

Example: "https://api.example.com/orders/{{order_id}}/status"
bodystring

The request body template. Supports template variables.

Example: "{\"text\": \"{{message}}\"}"
headersArray of objects

HTTP headers for the request. Header values are always redacted as "****" in responses.

Example: [{"name":"Authorization","value":"****"}]
http_methodstring

The HTTP method used by the data connector.

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

Whether this connector is used directly by Fin.

Example: false
audiencesArray of strings

The audience types this connector targets.

Items Enum"users""leads""visitors"
Example: ["users","leads"]
execution_typestring or null

How the connector executes.

Enum"server_side""client_side"
Example: "server_side"
configuration_response_typestring or null

The expected response format from the connector.

Enum"test_response_type""mock_response_type"
Example: "test_response_type"
data_transformation_typestring or null

The type of data transformation applied to the response.

Enum"full_access""redacted_access""code_block_transformation"
client_function_namestring or null

The name of the client-side function, if applicable.

client_function_timeout_msinteger or null

Timeout in milliseconds for the client function, if applicable.

data_inputsArray of objects

The input parameters accepted by this data connector.

response_fieldsArray of objects

The fields returned in the connector response.

object_mappingsArray of objects

Mappings from connector response objects to Intercom objects.

token_idsArray of strings

IDs of authentication tokens associated with this connector.

Example: []
customer_authenticationboolean

Whether OTP authentication is enabled for this connector.

Example: false
bypass_authenticationboolean

Whether authentication is bypassed for this connector.

Example: false
validate_missing_attributesboolean or null

Whether to validate missing attributes before execution.

created_by_admin_idstring or null

The ID of the admin who created this connector.

Example: "456"
updated_by_admin_idstring or null

The ID of the admin who last updated this connector.

Example: "456"
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": "Order Status Service",
  "description": "Fetches order status from external fulfillment API",
  "state": "live",
  "url": "https://api.example.com/orders/{{order_id}}/status",
  "body": "{\"text\": \"{{message}}\"}",
  "headers": [
    { … }
  ],
  "http_method": "post",
  "direct_fin_usage": false,
  "audiences": [
    "users",
    "leads"
  ],
  "execution_type": "server_side",
  "configuration_response_type": "test_response_type",
  "data_transformation_type": "full_access",
  "client_function_name": "string",
  "client_function_timeout_ms": 0,
  "data_inputs": [
    { … }
  ],
  "response_fields": [
    { … }
  ],
  "object_mappings": [
    { … }
  ],
  "token_ids": [],
  "customer_authentication": false,
  "bypass_authentication": false,
  "validate_missing_attributes": true,
  "created_by_admin_id": "456",
  "updated_by_admin_id": "456",
  "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

Returns a paginated list of all data connectors for the workspace, ordered by most recently updated first. Data connectors allow workflows and AI agents to make HTTP requests to external APIs.

Security
bearerAuth
Query
per_pageinteger[ 1 .. 50 ]

The number of results to return per page. Defaults to 20, minimum 1, maximum 50.

Default 20
starting_afterstring

The cursor value from pages.next.starting_after in a previous response. Used to paginate through results.

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?per_page=20&starting_after=string' \
  -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.

pagesobject

Pagination information.

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

Create a data connector

Request

Create a new data connector. The connector is created in draft state. Configure its URL, headers, data inputs, and other settings, then set it to live when ready.

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
Bodyapplication/json
namestringrequired

The name of the data connector.

Example: "Get Order Status"
descriptionstring

A description of what this data connector does.

Example: "Looks up order status from an external service"
http_methodstring

The HTTP method used when calling the external API.

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

The URL of the external API endpoint. Supports template variables like {{order_id}}.

Example: "https://api.example.com/orders/{{order_id}}/status"
bodystring

The request body template. Supports template variables.

direct_fin_usageboolean

Whether the connector is used directly by Fin (true) or only in workflows (false). Defaults to false.

Example: false
audiencesArray of strings

The user types this connector is available for.

Items Enum"leads""users""visitors"
Example: ["leads","visitors"]
headersArray of objects

HTTP headers to include in the request.

data_inputsArray of objects

Input parameters accepted by the connector.

customer_authenticationboolean

Whether the connector requires customer authentication before executing. Defaults to false.

Example: false
bypass_authenticationboolean

Whether authentication is bypassed entirely (public endpoint). Defaults to false.

Example: false
validate_missing_attributesboolean

Whether to validate that all required data inputs have values before executing.

Example: false
mock_responseobject

A sample JSON response from the external API. Auto-generates response_fields and sets configuration_response_type to mock_response_type.

Example: {"order":{"id":12345,"status":"shipped"}}
token_idsArray of strings

IDs of authentication tokens to attach to this data connector.

Example: ["1234","5678"]
curl -i -X POST \
  https://api.intercom.io/data_connectors \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Unstable' \
  -d '{
    "name": "Get Order Status",
    "description": "Looks up order status from an external service",
    "http_method": "get",
    "url": "https://api.example.com/orders/{{order_id}}/status",
    "direct_fin_usage": true,
    "audiences": [
      "leads",
      "visitors"
    ],
    "headers": [
      {
        "name": "Content-Type",
        "value": "application/json"
      }
    ],
    "data_inputs": [
      {
        "name": "order_id",
        "type": "string",
        "description": "The order ID to look up",
        "required": true,
        "default_value": ""
      }
    ],
    "customer_authentication": true,
    "bypass_authentication": false,
    "validate_missing_attributes": true
  }'

Responses

Data connector created

Bodyapplication/json
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: "Order Status Service"
descriptionstring or null

A description of what this data connector does.

Example: "Fetches order status from external fulfillment API"
statestring

The current state of the data connector.

Enum"draft""live"
Example: "live"
urlstring or null

The URL of the external API endpoint. Supports template variables like {{order_id}}.

Example: "https://api.example.com/orders/{{order_id}}/status"
bodystring

The request body template. Supports template variables.

Example: "{\"text\": \"{{message}}\"}"
headersArray of objects

HTTP headers for the request. Header values are always redacted as "****" in responses.

Example: [{"name":"Authorization","value":"****"}]
http_methodstring

The HTTP method used by the data connector.

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

Whether this connector is used directly by Fin.

Example: false
audiencesArray of strings

The audience types this connector targets.

Items Enum"users""leads""visitors"
Example: ["users","leads"]
execution_typestring or null

How the connector executes.

Enum"server_side""client_side"
Example: "server_side"
configuration_response_typestring or null

The expected response format from the connector.

Enum"test_response_type""mock_response_type"
Example: "test_response_type"
data_transformation_typestring or null

The type of data transformation applied to the response.

Enum"full_access""redacted_access""code_block_transformation"
client_function_namestring or null

The name of the client-side function, if applicable.

client_function_timeout_msinteger or null

Timeout in milliseconds for the client function, if applicable.

data_inputsArray of objects

The input parameters accepted by this data connector.

response_fieldsArray of objects

The fields returned in the connector response.

object_mappingsArray of objects

Mappings from connector response objects to Intercom objects.

token_idsArray of strings

IDs of authentication tokens associated with this connector.

Example: []
customer_authenticationboolean

Whether OTP authentication is enabled for this connector.

Example: false
bypass_authenticationboolean

Whether authentication is bypassed for this connector.

Example: false
validate_missing_attributesboolean or null

Whether to validate missing attributes before execution.

created_by_admin_idstring or null

The ID of the admin who created this connector.

Example: "456"
updated_by_admin_idstring or null

The ID of the admin who last updated this connector.

Example: "456"
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"
Response
application/json
{
  "type": "data_connector",
  "id": "125",
  "name": "Get Order Status",
  "description": "Looks up order status from an external service",
  "state": "draft",
  "http_method": "get",
  "direct_fin_usage": true,
  "audiences": [
    "leads",
    "visitors"
  ],
  "execution_type": "server_side",
  "configuration_response_type": "test_response_type",
  "data_transformation_type": "full_access",
  "client_function_timeout_ms": 30000,
  "data_inputs": [
    { … }
  ],
  "response_fields": [],
  "object_mappings": [],
  "token_ids": [],
  "customer_authentication": true,
  "bypass_authentication": false,
  "validate_missing_attributes": true,
  "created_by_admin_id": "128",
  "updated_by_admin_id": "128",
  "created_at": "2026-03-19T11:27:36Z",
  "updated_at": "2026-03-19T11:27:36Z",
  "execution_results_url": "/data_connectors/125/execution_results"
}

Retrieve a data connector

Request

You can retrieve the full detail of a single data connector by its ID.

The response includes configuration, data inputs, response fields, and object mappings.

Security
bearerAuth
Path
idstringrequired

The unique identifier of the data connector.

Example: 12345
Query
state_versionstring

Which version of the data connector to return. Defaults to live.

Default "live"
Enum"draft""live"
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?state_version=draft' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: Unstable'

Responses

Data connector found

Bodyapplication/json
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: "Order Status Service"
descriptionstring or null

A description of what this data connector does.

Example: "Fetches order status from external fulfillment API"
statestring

The current state of the data connector.

Enum"draft""live"
Example: "live"
urlstring or null

The URL of the external API endpoint. Supports template variables like {{order_id}}.

Example: "https://api.example.com/orders/{{order_id}}/status"
bodystring

The request body template. Supports template variables.

Example: "{\"text\": \"{{message}}\"}"
headersArray of objects

HTTP headers for the request. Header values are always redacted as "****" in responses.

Example: [{"name":"Authorization","value":"****"}]
http_methodstring

The HTTP method used by the data connector.

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

Whether this connector is used directly by Fin.

Example: false
audiencesArray of strings

The audience types this connector targets.

Items Enum"users""leads""visitors"
Example: ["users","leads"]
execution_typestring or null

How the connector executes.

Enum"server_side""client_side"
Example: "server_side"
configuration_response_typestring or null

The expected response format from the connector.

Enum"test_response_type""mock_response_type"
Example: "test_response_type"
data_transformation_typestring or null

The type of data transformation applied to the response.

Enum"full_access""redacted_access""code_block_transformation"
client_function_namestring or null

The name of the client-side function, if applicable.

client_function_timeout_msinteger or null

Timeout in milliseconds for the client function, if applicable.

data_inputsArray of objects

The input parameters accepted by this data connector.

response_fieldsArray of objects

The fields returned in the connector response.

object_mappingsArray of objects

Mappings from connector response objects to Intercom objects.

token_idsArray of strings

IDs of authentication tokens associated with this connector.

Example: []
customer_authenticationboolean

Whether OTP authentication is enabled for this connector.

Example: false
bypass_authenticationboolean

Whether authentication is bypassed for this connector.

Example: false
validate_missing_attributesboolean or null

Whether to validate missing attributes before execution.

created_by_admin_idstring or null

The ID of the admin who created this connector.

Example: "456"
updated_by_admin_idstring or null

The ID of the admin who last updated this connector.

Example: "456"
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"
Response
application/json
{
  "type": "data_connector",
  "id": "12345",
  "name": "Order Status Service",
  "description": "Fetches order status from external fulfillment API",
  "state": "live",
  "http_method": "post",
  "direct_fin_usage": false,
  "audiences": [
    "users",
    "leads"
  ],
  "execution_type": "server_side",
  "configuration_response_type": "test_response_type",
  "data_transformation_type": null,
  "client_function_name": null,
  "client_function_timeout_ms": null,
  "data_inputs": [
    { … }
  ],
  "response_fields": [
    { … }
  ],
  "object_mappings": [],
  "token_ids": [],
  "customer_authentication": false,
  "bypass_authentication": false,
  "validate_missing_attributes": null,
  "created_by_admin_id": "456",
  "updated_by_admin_id": "456",
  "created_at": "2025-11-15T09:30:00Z",
  "updated_at": "2026-01-20T14:22:15Z",
  "execution_results_url": "/data_connectors/12345/execution_results"
}

Delete a data connector

Request

Delete an existing data connector. The connector must be in draft state and must not be in use by any workflows or AI agents.

Security
bearerAuth
Path
idstringrequired

The unique identifier of the data connector

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

Responses

Data connector deleted

Bodyapplication/json
idstring

The unique identifier for the data connector.

Example: "125"
objectstring

The type of object which was deleted.

Value"data_connector"
Example: "data_connector"
deletedboolean

Whether the data connector was deleted successfully.

Example: true
Response
application/json
{
  "id": "125",
  "object": "data_connector",
  "deleted": true
}

Update a data connector

Request

Update an existing data connector. Only provided fields are changed. Set state to live or draft to change the connector's state.

Security
bearerAuth
Path
idstringrequired

The unique identifier of the data connector.

Example: 12345
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
namestring

The name of the data connector.

Example: "Updated Connector Name"
descriptionstring

A description of what this data connector does.

Example: "Updated description"
statestring

The desired state of the connector.

Enum"draft""live"
http_methodstring

The HTTP method used by the data connector.

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

The URL of the external API endpoint. Supports template variables like {{order_id}}.

Example: "https://api.example.com/orders/{{order_id}}/status"
bodystring

The request body template. Supports template variables.

direct_fin_usageboolean

Whether this connector is used directly by Fin.

Example: false
audiencesArray of strings

The audience types this connector targets.

Items Enum"leads""users""visitors"
Example: ["leads","users"]
headersArray of objects

HTTP headers to include in the request.

data_inputsArray of objects

The input parameters accepted by this data connector. Replaces all existing inputs.

customer_authenticationboolean

Whether OTP authentication is enabled for this connector.

Example: false
bypass_authenticationboolean

Whether authentication is bypassed for this connector.

Example: false
validate_missing_attributesboolean

Whether to validate missing attributes before execution.

Example: true
mock_responseobject

A sample JSON response from the external API. Auto-generates response_fields and sets configuration_response_type to mock_response_type.

Example: {"order":{"id":12345,"status":"shipped"}}
token_idsArray of strings

IDs of authentication tokens to attach to this data connector. An empty array removes all tokens.

Example: ["1234","5678"]
curl -i -X PATCH \
  https://api.intercom.io/data_connectors/12345 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Unstable' \
  -d '{
    "name": "Updated Connector Name",
    "description": "Updated description"
  }'

Responses

Data connector updated

Bodyapplication/json
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: "Order Status Service"
descriptionstring or null

A description of what this data connector does.

Example: "Fetches order status from external fulfillment API"
statestring

The current state of the data connector.

Enum"draft""live"
Example: "live"
urlstring or null

The URL of the external API endpoint. Supports template variables like {{order_id}}.

Example: "https://api.example.com/orders/{{order_id}}/status"
bodystring

The request body template. Supports template variables.

Example: "{\"text\": \"{{message}}\"}"
headersArray of objects

HTTP headers for the request. Header values are always redacted as "****" in responses.

Example: [{"name":"Authorization","value":"****"}]
http_methodstring

The HTTP method used by the data connector.

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

Whether this connector is used directly by Fin.

Example: false
audiencesArray of strings

The audience types this connector targets.

Items Enum"users""leads""visitors"
Example: ["users","leads"]
execution_typestring or null

How the connector executes.

Enum"server_side""client_side"
Example: "server_side"
configuration_response_typestring or null

The expected response format from the connector.

Enum"test_response_type""mock_response_type"
Example: "test_response_type"
data_transformation_typestring or null

The type of data transformation applied to the response.

Enum"full_access""redacted_access""code_block_transformation"
client_function_namestring or null

The name of the client-side function, if applicable.

client_function_timeout_msinteger or null

Timeout in milliseconds for the client function, if applicable.

data_inputsArray of objects

The input parameters accepted by this data connector.

response_fieldsArray of objects

The fields returned in the connector response.

object_mappingsArray of objects

Mappings from connector response objects to Intercom objects.

token_idsArray of strings

IDs of authentication tokens associated with this connector.

Example: []
customer_authenticationboolean

Whether OTP authentication is enabled for this connector.

Example: false
bypass_authenticationboolean

Whether authentication is bypassed for this connector.

Example: false
validate_missing_attributesboolean or null

Whether to validate missing attributes before execution.

created_by_admin_idstring or null

The ID of the admin who created this connector.

Example: "456"
updated_by_admin_idstring or null

The ID of the admin who last updated this connector.

Example: "456"
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"
Response
application/json
{
  "type": "data_connector",
  "id": "12345",
  "name": "Updated Connector Name",
  "description": "Updated description",
  "state": "draft",
  "http_method": "post",
  "direct_fin_usage": false,
  "audiences": [
    "users",
    "leads"
  ],
  "execution_type": "server_side",
  "configuration_response_type": "test_response_type",
  "data_transformation_type": null,
  "client_function_name": null,
  "client_function_timeout_ms": null,
  "data_inputs": [
    { … }
  ],
  "response_fields": [],
  "object_mappings": [],
  "token_ids": [],
  "customer_authentication": false,
  "bypass_authentication": false,
  "validate_missing_attributes": false,
  "created_by_admin_id": "456",
  "updated_by_admin_id": "456",
  "created_at": "2025-11-15T09:30:00Z",
  "updated_at": "2026-03-24T14:22:15Z",
  "execution_results_url": "/data_connectors/12345/execution_results"
}

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

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

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

Export

Operations

Folders

SchemasOperations

WhatsApp

Operations