Intercom API (unofficial showcase)
POST/data_connectors

Create a data connector

Creates a new data connector for calling an external API. Provide name and any configuration fields; the connector starts in draft state. Configure its settings before setting it to live.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 14 body fields
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Configuration for a new data connector. name is required.

namestringrequired
The name of the data connector.
descriptionstringoptional
A description of what this data connector does.
http_methodstringoptional
The HTTP method used when calling the external API.
Allowed:getpostputdeletepatch
urlstringoptional
The URL of the external API endpoint. Supports template variables like `{{order_id}}`.
bodystringoptional
The request body template. Supports template variables.
direct_fin_usagebooleanoptional
Whether the connector is used directly by Fin (true) or only in workflows (false). Defaults to false.
audiencesarray<string>optional
The user types this connector is available for.
headersarray<object>optional
HTTP headers to include in the request.
data_inputsarray<object>optional
Input parameters accepted by the connector.
customer_authenticationbooleanoptional
Whether the connector requires customer authentication before executing. Defaults to false.
bypass_authenticationbooleanoptional
Whether authentication is bypassed entirely (public endpoint). Defaults to false.
validate_missing_attributesbooleanoptional
Whether to validate that all required data inputs have values before executing.
mock_responseobjectoptional
A sample JSON response from the external API. Auto-generates `response_fields` and sets `configuration_response_type` to `mock_response_type`.
token_idsarray<string>optional
IDs of authentication tokens to attach to this data connector.

3 status codes
201Returns the created data connector, including its identifier, name, draft state, and configuration.
typestringoptional
The type of object - `data_connector`.
Allowed:data_connector
idstringoptional
The unique identifier for the data connector.
namestringoptional
The name of the data connector.
descriptionstringoptional
A description of what this data connector does.
statestringoptional
The current state of the data connector.
Allowed:draftlive
urlstringoptional
The URL of the external API endpoint. Supports template variables like `{{order_id}}`.
bodystringoptional
The request body template. Supports template variables.
headersarray<object>optional
HTTP headers for the request. Header values are always redacted as `"****"` in responses.
http_methodstringoptional
The HTTP method used by the data connector.
Allowed:getpostputdeletepatch
direct_fin_usagebooleanoptional
Whether this connector is used directly by Fin.
audiencesarray<string>optional
The audience types this connector targets.
execution_typestringoptional
How the connector executes.
Allowed:server_sideclient_side
configuration_response_typestringoptional
The expected response format from the connector.
Allowed:test_response_typemock_response_type
data_transformation_typestringoptional
The type of data transformation applied to the response.
Allowed:full_accessredacted_accesscode_block_transformation
client_function_namestringoptional
The name of the client-side function, if applicable.
client_function_timeout_msintegeroptional
Timeout in milliseconds for the client function, if applicable.
data_inputsarray<object>optional
The input parameters accepted by this data connector.
response_fieldsarray<object>optional
The fields returned in the connector response.
object_mappingsarray<object>optional
Mappings from connector response objects to Intercom objects.
token_idsarray<string>optional
IDs of authentication tokens associated with this connector.
customer_authenticationbooleanoptional
Whether OTP authentication is enabled for this connector.
bypass_authenticationbooleanoptional
Whether authentication is bypassed for this connector.
validate_missing_attributesbooleanoptional
Whether to validate missing attributes before execution.
created_by_admin_idstringoptional
The ID of the admin who created this connector.
updated_by_admin_idstringoptional
The ID of the admin who last updated this connector.
created_atstringoptional
The time the data connector was created.
updated_atstringoptional
The time the data connector was last updated.
execution_results_urlstringoptional
The URL path to fetch execution results for this connector.
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
422Returned when a parameter is invalid.

2 documented failures

  • parameter_not_found

    Name is required

  • parameter_invalid

    Invalid audiences. Must be a subset of: leads, users, visitors

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 401 is returned when the request is unauthorized, and a 422 when a parameter is invalid. name is required; http_method must be one of get, post, put, delete, or patch, and audience values must be leads, users, or visitors.