Create a data connector

REST API Reference

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.

OAuth tokens must have the read_write_data_connectors scope.

Security

bearerAuth

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

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"

internal_descriptionstring

The internal description of the data connector. If omitted, it is an empty string.

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

enforce_authboolean

Whether authentication is enforced. On workspaces where this is supported, it takes precedence over customer_authentication and bypass_authentication when sent together, and setting it to false disables OTP.

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: 2.17' \
  -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"

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": "125",
  "name": "Get Order Status",
  "description": "Looks up order status from an external service",
  "internal_description": "",
  "state": "draft",
  "url": "https://api.example.com/orders/{{order_id}}/status",
  "headers": [
    { … }
  ],
  "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,
  "enforce_auth": true,
  "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"
}

Request

Headers

Responses

Was this page helpful?