# List versions of a data connector

Retrieve the version history of a data connector, newest first. Each entry is a point-in-time snapshot of the connector's configuration, with the status it has today and an optional note.
Results are paginated. `pages.next` is omitted on the last page. A data connector that has never been published returns an empty `data` list.
Requires the `read_data_connector_versions` or `read_write_data_connector_versions` OAuth scope. Set `Intercom-Version: Preview`.

Endpoint: GET /data_connectors/{id}/versions
Version: Preview
Security: bearerAuth

## Path parameters:

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

## Query parameters:

  - `per_page` (integer)
    The number of results per page (1-50, default 20). Values outside this range are clamped, so values below 1 are treated as 1. A non-integer value falls back to the default of 20.

  - `starting_after` (string)
    Cursor for pagination. Use the value from `pages.next.starting_after` in a previous response.

## Header parameters:

  - `Intercom-Version` (string)

## Response 200 fields (application/json):

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

  - `data` (array)
    An array of data connector version objects.

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

  - `data.status` (string)
    The status of this version today.
    Enum: "live", "paused", "draft", "previously_live"

  - `data.note` (string)
    A note describing this version, if one has been set.
    Example: Switched to the v2 orders endpoint

  - `data.author` (object)
    The teammate who created this version.

  - `data.author.id` (integer)
    The unique identifier of the teammate.
    Example: 456

  - `data.author.name` (string)
    The name of the teammate.
    Example: Alice Admin

  - `data.created_at` (string)
    The time this version was created.
    Example: 2026-09-14T10:02:11Z

  - `data.entity_version_id` (integer)
    The identifier of this version. Use it as `version_id` when retrieving or updating a version.
    Example: 9821

  - `data.definition` (object)
    The data connector's configuration at this version. `null` if the snapshot is no longer available. Mirrors the response of [Retrieve a data connector](/docs/references/preview/rest-api/api.intercom.io/data-connectors/retrievedataconnector), without `id`, `type`, `created_by_admin_id`, `updated_by_admin_id`, `created_at`, `updated_at`, `execution_results_url` and `transform_code_block`.

  - `data.definition.name` (string)
    The name of the data connector.
    Example: Order Status Service

  - `data.definition.description` (string)
    A description of what this data connector does.

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

  - `data.definition.state` (string)
    The state of the data connector at this version.
    Example: live

  - `data.definition.url` (string)
    The URL of the external API endpoint. Supports template variables like `{{order_id}}`.

  - `data.definition.body` (string)
    The request body template. Supports template variables.

  - `data.definition.headers` (array)
    HTTP headers for the request. Header values are always redacted as `"****"`.

  - `data.definition.headers.name` (string)
    Example: Authorization

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

  - `data.definition.http_method` (string)
    The HTTP method used by the data connector.
    Example: get

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

  - `data.definition.audiences` (array)
    The audience types this connector targets.

  - `data.definition.execution_type` (string)
    How the connector executes, for example `server_side` or `client_side`.

  - `data.definition.configuration_response_type` (string)
    The expected response format from the connector.

  - `data.definition.data_transformation_type` (string)
    The type of data transformation applied to the response.

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

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

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

  - `data.definition.data_inputs.name` (string)

  - `data.definition.data_inputs.type` (string)

  - `data.definition.data_inputs.description` (string)

  - `data.definition.data_inputs.required` (boolean)

  - `data.definition.data_inputs.default_value` (any)

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

  - `data.definition.response_fields.path` (string)

  - `data.definition.response_fields.type` (string)

  - `data.definition.response_fields.example_value` (any)

  - `data.definition.response_fields.redacted` (boolean)

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

  - `data.definition.object_mappings.response_object_path` (string)

  - `data.definition.object_mappings.intercom_object_type` (string)

  - `data.definition.object_mappings.attribute_mappings` (array)

  - `data.definition.object_mappings.attribute_mappings.response_attribute_path` (string)

  - `data.definition.object_mappings.attribute_mappings.intercom_attribute_identifier` (string)

  - `data.definition.object_mappings.attribute_mappings.mapping_type` (string)

  - `data.definition.object_mappings.reference_mappings` (array)

  - `data.definition.object_mappings.reference_mappings.intercom_object_type` (string)

  - `data.definition.object_mappings.reference_mappings.intercom_attribute_identifier` (string)

  - `data.definition.token_ids` (array)
    IDs of authentication tokens associated with this connector.

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

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

  - `data.definition.enforce_auth` (boolean)
    Whether authentication is enforced for this connector.

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

  - `pages` (object)
    Pagination information. `next` is omitted on the last page.

  - `pages.type` (string)
    Enum: "pages"

  - `pages.per_page` (integer)
    The number of results per page.
    Example: 20

  - `pages.next` (object)
    Cursor for the next page of results.

  - `pages.next.starting_after` (string)
    The cursor value to use for the next page.
    Example: WzQ0MDksNDQwOSxudWxsXQ==

## 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

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

## 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

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

## 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

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