Get Custom Object Instance by ID

Request

Fetch a Custom Object Instance by id.

Requires the read_conversations, read_users_companies, read_write_custom_object_instances or read_write_users OAuth scope.

Security

bearerAuth

Path

custom_object_instance_idstringrequired

The Intercom defined id of the custom object instance. An external id here is not looked up; to find an instance by its external id, call GET /custom_object_instances/{custom_object_type_identifier}?external_id=.

custom_object_type_identifierstringrequired

The unique identifier of the custom object type that defines the structure of the custom object instance.

Example:Order

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

curl -i -X GET \
  'https://api.intercom.io/custom_object_instances/Order/{custom_object_instance_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.17'

Responses

successful. If the custom object type exists but no instance matches, the response is still 200 with found: false.

Bodyapplication/json

One of:

A Custom Object Instance represents an instance of a custom object type. This allows you to create and set custom attributes to store data about your customers that is not already captured by Intercom. The parent object includes recommended default attributes and you can add your own custom attributes.

idstring

The Intercom defined id representing the custom object instance.

Example:16032025

external_idstring

The id you have defined for the custom object instance.

Example:"0001d1c1e65a7a19e9f59ae2"

external_created_atinteger or null, (date-time)

The time when the Custom Object instance was created in the external system it originated from.

Example:1571672154

external_updated_atinteger or null, (date-time)

The time when the Custom Object instance was last updated in the external system it originated from.

Example:1571672154

created_atinteger, (date-time)

The time the attribute was created as a UTC Unix timestamp

Example:1671028894

updated_atinteger, (date-time)

The time the attribute was last updated as a UTC Unix timestamp

Example:1671028894

typestring

The identifier of the custom object type that defines the structure of the custom object instance.

Example:"Order"

custom_attributesobject

The custom attributes you have set on the custom object instance.

Each value is returned with the type of the attribute it is set on: a string, integer, number or boolean, or null when the attribute is unset. A list attribute returns the label of the selected option. A reference attribute returns an object holding the referenced records, under contacts for a contact reference, conversations for a conversation reference, or instances for a reference to another custom object type.

Example:

{
  "order_number": "ORDER-12345",
  "total_amount": 99.99
}

Response

{
  "id": "25",
  "type": "Order",
  "custom_attributes": {
    "order_number": "ORDER-12345",
    "total_amount": 99.99
  },
  "external_id": "123",
  "external_created_at": null,
  "external_updated_at": null,
  "created_at": 1734537750,
  "updated_at": 1734537750
}