# Create a data connector

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

Endpoint: POST /data_connectors
Version: Unstable
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)
    Intercom API version.By default, it's equal to the version set in the app package.
    Enum: "1.0", "1.1", "1.2", "1.3", "1.4", "2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13", "2.14", "Unstable"

## Request fields (application/json):

  - `name` (string, required)
    The name of the data connector.
    Example: "Get Order Status"

  - `description` (string)
    A description of what this data connector does.
    Example: "Looks up order status from an external service"

  - `http_method` (string)
    The HTTP method used when calling the external API.
    Enum: "get", "post", "put", "delete", "patch"

  - `url` (string)
    The URL of the external API endpoint. Supports template variables like {{order_id}}.
    Example: "https://api.example.com/orders/{{order_id}}/status"

  - `body` (string,null)
    The request body template. Supports template variables.

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

  - `audiences` (array)
    The user types this connector is available for.
    Enum: "leads", "users", "visitors"

  - `headers` (array)
    HTTP headers to include in the request.

  - `headers.name` (string)
    The header name.
    Example: "Content-Type"

  - `headers.value` (string)
    The header value. Supports template variables.
    Example: "application/json"

  - `data_inputs` (array)
    Input parameters accepted by the connector.

  - `data_inputs.name` (string)
    The parameter name.
    Example: "order_id"

  - `data_inputs.type` (string)
    The parameter type.
    Enum: "string", "integer", "decimal", "boolean"

  - `data_inputs.description` (string)
    A description of the parameter.
    Example: "The order ID to look up"

  - `data_inputs.required` (boolean)
    Whether the parameter is required.
    Example: true

  - `data_inputs.default_value` (string)
    The default value for the parameter. Defaults to an empty string if omitted.

  - `customer_authentication` (boolean)
    Whether the connector requires customer authentication before executing. Defaults to false.

  - `bypass_authentication` (boolean)
    Whether authentication is bypassed entirely (public endpoint). Defaults to false.

  - `validate_missing_attributes` (boolean)
    Whether to validate that all required data inputs have values before executing.

## Response 201 fields (application/json):

  - `type` (string)
    The type of object - data_connector.
    Enum: "data_connector"

  - `id` (string)
    The unique identifier for the data connector.
    Example: "12345"

  - `name` (string)
    The name of the data connector.
    Example: "Slack Notification Service"

  - `description` (string,null)
    A description of what this data connector does.
    Example: "Posts conversation updates to Slack channel"

  - `state` (string)
    The current state of the data connector.
    Enum: "draft", "live"

  - `http_method` (string)
    The HTTP method used by the data connector.
    Enum: "get", "post", "put", "delete", "patch"

  - `direct_fin_usage` (boolean)
    Whether this connector is used directly by Fin.

  - `audiences` (array)
    The audience types this connector targets.
    Enum: "users", "leads", "visitors"

  - `execution_type` (string,null)
    How the connector executes.
    Enum: "server_side", "client_side"

  - `configuration_response_type` (string,null)
    The expected response format from the connector.
    Enum: "test_response_type", "mock_response_type"

  - `data_transformation_type` (string,null)
    The type of data transformation applied to the response.
    Enum: "full_access", "redacted_access", "code_block_transformation"

  - `client_function_name` (string,null)
    The name of the client-side function, if applicable.

  - `client_function_timeout_ms` (integer,null)
    Timeout in milliseconds for the client function, if applicable.

  - `data_inputs` (array)
    The input parameters accepted by this data connector.

  - `data_inputs.name` (string)
    The name of the input parameter.
    Example: "conversation_id"

  - `data_inputs.type` (string)
    The data type of the input.
    Enum: "string", "integer", "decimal", "boolean"

  - `data_inputs.description` (string,null)
    A description of the input parameter.

  - `data_inputs.required` (boolean)
    Whether this input is required.
    Example: true

  - `data_inputs.default_value` (string)
    The default value for this input, if any.

  - `response_fields` (array)
    The fields returned in the connector response.

  - `response_fields.path` (string)
    The JSON path of the response field.
    Example: "status"

  - `response_fields.type` (string)
    The data type of the response field.
    Enum: "unknown", "string", "integer", "decimal", "datetime", "boolean"

  - `response_fields.example_value` (any,null)
    An example value for this field.
    Example: "ok"

  - `response_fields.redacted` (boolean)
    Whether this field is redacted in logs.

  - `object_mappings` (array)
    Mappings from connector response objects to Intercom objects.

  - `object_mappings.response_object_path` (string)

  - `object_mappings.intercom_object_type` (string)
    Enum: "conversation", "user"

  - `object_mappings.attribute_mappings` (array)

  - `object_mappings.attribute_mappings.response_attribute_path` (string)

  - `object_mappings.attribute_mappings.intercom_attribute_identifier` (string)

  - `object_mappings.attribute_mappings.mapping_type` (string)
    Enum: "primitive_mapping", "context_mapping"

  - `object_mappings.reference_mappings` (array)

  - `token_ids` (array)
    IDs of authentication tokens associated with this connector.
    Example: []

  - `customer_authentication` (boolean)
    Whether OTP authentication is enabled for this connector.

  - `bypass_authentication` (boolean)
    Whether authentication is bypassed for this connector.

  - `validate_missing_attributes` (boolean,null)
    Whether to validate missing attributes before execution.

  - `created_by_admin_id` (string,null)
    The ID of the admin who created this connector.
    Example: "456"

  - `updated_by_admin_id` (string,null)
    The ID of the admin who last updated this connector.
    Example: "456"

  - `created_at` (string)
    The time the data connector was created.
    Example: "2025-11-15T09:30:00Z"

  - `updated_at` (string)
    The time the data connector was last updated.
    Example: "2026-01-20T14:22:15Z"

  - `execution_results_url` (string)
    The URL path to fetch execution results for this connector.
    Example: "/data_connectors/12345/execution_results"

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: "error.list"

  - `request_id` (string,null)
    Example: "f93ecfa8-d08a-4325-8694-89aeb89c8f85"

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code
    Example: "unauthorized"

  - `errors.message` (string,null)
    Optional. Human readable description of the error.
    Example: "Access Token Invalid"

  - `errors.field` (string,null)
    Optional. Used to identify a particular field or query parameter that was in error.
    Example: "email"

## Response 422 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: "error.list"

  - `request_id` (string,null)
    Example: "f93ecfa8-d08a-4325-8694-89aeb89c8f85"

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code
    Example: "unauthorized"

  - `errors.message` (string,null)
    Optional. Human readable description of the error.
    Example: "Access Token Invalid"

  - `errors.field` (string,null)
    Optional. Used to identify a particular field or query parameter that was in error.
    Example: "email"