Intercom API (unofficial showcase)
GET/custom_object_instances/{custom_object_type_identifier}

List custom object instances

Lists instances of a custom object type, optionally filtered by an associated contact or conversation. Use references_contact_id or references_conversation_id to filter the results, or provide external_id to retrieve a single matching instance instead of a list. Use page and per_page to paginate the results.

7 parameters
custom_object_type_identifierstringrequired
The unique identifier of the custom object type that defines the instance structure.
references_contact_idstringoptional
Filter results to instances associated with this contact ID.
references_conversation_idstringoptional
Filter results to instances associated with this conversation ID.
external_idstringoptional
Return the single instance with this external ID instead of a list.
pageintegeroptional
The page number of results to fetch.
per_pageintegeroptional
The number of results per page. Maximum 150.
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted; use a supported version.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

3 status codes
200Returns custom object instance data. Without `external_id`, the response contains a paginated list and total count; with `external_id`, it contains the single matching instance.
typestringoptional
The type of the object - `list`.
Allowed:list
pagesobjectoptional
The majority of list resources in the API are paginated to allow clients to traverse data over multiple requests. Their responses are likely to contain a pages object that hosts pagination links which a client can use to paginate through the data without having to construct a query. The link relations for the pages field are as follows.
total_countintegeroptional
A count of the total number of custom object instances.
dataarray<CustomObjectInstance>optional
An array of Custom Object Instance objects.
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
404Returned when the custom object type or requested instance is not found.

One documented failure

  • not_found

    Custom object type `undefined` not found

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 401 is returned when the request is unauthorized, and a 404 is returned when the custom object type or requested instance is not found. The custom_object_type_identifier path parameter must identify the custom object type; per_page accepts at most 150.