Skip to content
Home/
REST API Reference
/
/
Retrieve a data connector

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.

OAuth tokens must have the read_workflow_connector_execution_result or read_write_data_connectors scope.

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.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:2.17
curl -i -X GET \
  'https://api.intercom.io/data_connectors/12345?state_version=draft' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.17'

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"
internal_descriptionstring

The internal description of the data connector.

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

How the connector executes.

Enum:"server_side""client_side"
Example:"server_side"
configuration_response_typestring

The expected response format from the connector.

Enum:"test_response_type""mock_response_type"
Example:"test_response_type"
data_transformation_typestring

The type of data transformation applied to the response.

Enum:"full_access""redacted_access""code_block_transformation"
transform_code_blockobject

The code block used to transform the connector's response. Present only when data_transformation_type is code_block_transformation and a code block exists; otherwise omitted.

Example:
{
  "code": "def transform(response):\n    return {\"status\": response[\"order_status\"]}\n\nreturn transform(inputs['data'])\n",
  "language": "python"
}
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
enforce_authboolean

Whether authentication is enforced for this connector.

Example:true
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
{
  "type": "data_connector",
  "id": "12345",
  "name": "Order Status Service",
  "description": "Fetches order status from external fulfillment API",
  "state": "live",
  "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_timeout_ms": 30000,
  "data_inputs": [
    { … }
  ],
  "response_fields": [
    { … }
  ],
  "object_mappings": [],
  "token_ids": [],
  "customer_authentication": false,
  "bypass_authentication": false,
  "enforce_auth": true,
  "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"
}