# Update a data connector

Update an existing data connector. Only provided fields are changed. Set `state` to `live` or `draft` to change the connector's state.
OAuth tokens must have the `read_write_data_connectors` scope.

Endpoint: PATCH /data_connectors/{id}
Version: 2.18
Security: bearerAuth

## Path parameters:

  - `id` (string, required)
    The unique identifier of the data connector.

## Header parameters:

  - `Intercom-Version` (string)

## Request fields (application/json):

  - `name` (string)
    The name of the data connector.
    Example: Updated Connector Name

  - `description` (string)
    A description of what this data connector does.
    Example: Updated description

  - `internal_description` (string)
    The internal description of the data connector. If omitted, it keeps its current value, unless the connector has no internal description yet, in which case it is set to the connector's `description`.

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

  - `http_method` (string)
    The HTTP method used by the data connector.
    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)
    The request body template. Supports template variables.

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

  - `audiences` (array)
    The audience types this connector targets.
    Example: ["leads","users"]

  - `headers` (array)
    HTTP headers to include in the request. Don't put credentials such as API keys here: header values are recorded unmasked in the connector's execution logs, except `Authorization`, which is always masked. Attach an authentication token with `token_ids` instead; its value is masked in execution logs.

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

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

  - `data_inputs` (array)
    The input parameters accepted by this data connector. Replaces all existing inputs.

  - `data_inputs.name` (string, required)
    The name of the input parameter.
    Example: order_id

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

  - `data_inputs.description` (string, required)
    A description of the input parameter. Required for each input.
    Example: The order ID to look up

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

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

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

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

  - `enforce_auth` (boolean)
    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_attributes` (boolean)
    Whether to validate missing attributes before execution.
    Example: true

  - `mock_response` (object)
    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_ids` (array)
    IDs of authentication tokens to attach to this data connector. An empty array removes all tokens.
    Example: ["1234","5678"]

## Response 200 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: Order Status Service

  - `description` (string)
    A description of what this data connector does.
    Example: Fetches order status from external fulfillment API

  - `internal_description` (string)
    The internal description of the data connector.

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

  - `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)
    The request body template. Supports template variables.
    Example: {"text": "{{message}}"}

  - `headers` (array)
    HTTP headers for the request. Header values are always redacted as `"****"` in responses.
    Example: [{"name":"Authorization","value":"****"}]

  - `headers.name` (string)
    The header name.
    Example: Authorization

  - `headers.value` (string)
    Always `"****"` in responses.
    Example: ****

  - `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.
    Example: false

  - `audiences` (array)
    The audience types this connector targets.
    Example: ["users","leads"]

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

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

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

  - `transform_code_block` (object)
    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"}

  - `transform_code_block.code` (string)
    The source code of the transform code block. The API response body is available as `inputs['data']`. The code must `return` the transformed value.
    Example: def transform(response):
    return {"status": response["order_status"]}

return transform(inputs['data'])


  - `transform_code_block.language` (string)
    The programming language of the transform code block. Currently always `python`.
    Example: python

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

  - `client_function_timeout_ms` (integer)
    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)
    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)
    An example value for this field.
    Example: ok

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

  - `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)

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

  - `object_mappings.reference_mappings.intercom_attribute_identifier` (string)

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

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

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

  - `enforce_auth` (boolean)
    Whether authentication is enforced for this connector.
    Example: true

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

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

  - `updated_by_admin_id` (string)
    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 400 fields (application/json):

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

  - `request_id` (string)
    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)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 401 fields (application/json):

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

  - `request_id` (string)
    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)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 404 fields (application/json):

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

  - `request_id` (string)
    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)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 409 fields (application/json):

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

  - `request_id` (string)
    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)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 422 fields (application/json):

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

  - `request_id` (string)
    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)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

