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

Update a data connector

Request

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.

Security
bearerAuth
Path
idstringrequired

The unique identifier of the data connector.

Example:12345
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
Bodyapplication/json
namestring

The name of the data connector.

Example:"Updated Connector Name"
descriptionstring

A description of what this data connector does.

Example:"Updated description"
internal_descriptionstring

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.

statestring

The desired state of the connector.

Enum:"draft""live"
http_methodstring

The HTTP method used by the data connector.

Enum:"get""post""put""delete""patch"
Example:"post"
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 this connector is used directly by Fin.

Example:false
audiencesArray of strings

The audience types this connector targets.

Items Enum:"leads""users""visitors"
Example:
[
  "leads",
  "users"
]
headersArray of objects

HTTP headers to include in the request.

data_inputsArray of objects

The input parameters accepted by this data connector. Replaces all existing inputs.

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. 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 missing attributes before execution.

Example:true
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. An empty array removes all tokens.

Example:
[
  "1234",
  "5678"
]
curl -i -X PATCH \
  https://api.intercom.io/data_connectors/12345 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.17' \
  -d '{
    "name": "Updated Connector Name",
    "description": "Updated description"
  }'

Responses

Data connector updated

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": "Updated Connector Name",
  "description": "Updated description",
  "state": "draft",
  "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": false,
  "created_by_admin_id": "456",
  "updated_by_admin_id": "456",
  "created_at": "2025-11-15T09:30:00Z",
  "updated_at": "2026-03-24T14:22:15Z",
  "execution_results_url": "/data_connectors/12345/execution_results"
}