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.

Security

bearerAuth

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"2.16"

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:2.16

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: 2.16' \
  -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

{
  "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"
}

Request

Headers

Responses

Was this page helpful?