Skip to content
Home/
REST API Reference
/
/
Create or Update a Custom...

Create or Update a Custom Object Instance

Request

Create or update a custom object instance

Requires the read_write_custom_object_instances OAuth scope.

Security
bearerAuth
Path
custom_object_type_identifierstringrequired

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

Example:Order
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:Preview
Bodyapplication/json
external_idstring

A unique identifier for the Custom Object instance in the external system it originated from. The value reference_not_found is reserved and is rejected with a 400. Omitting this field creates a new instance on every request instead of updating an existing one.

external_created_atinteger or null, (date-time)

The time when the Custom Object instance was created in the external system it originated from. A value that cannot be read as a time is stored as null rather than rejected.

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. A value that cannot be read as a time is stored as null rather than rejected.

Example:1571672154
custom_attributesobject or null

The custom attributes which are set for the Custom Object instance.

Each value must match the type of the attribute it is set on: a string, integer, number or boolean, a Unix timestamp or date string for a datetime attribute, or null to clear the attribute. A list attribute takes the label or id of one of its options; a value that matches no option clears the attribute rather than being rejected. A reference attribute takes the Intercom id of the record it points at, or an array of ids for a reference to several records; an id that matches no record is skipped.

Example:
{
  "order_number": "ORDER-12345",
  "total_amount": 99.99
}
curl -i -X POST \
  https://api.intercom.io/custom_object_instances/Order \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "external_id": "123",
    "external_created_at": 1392036272,
    "external_updated_at": 1392036272,
    "custom_attributes": {
      "order_number": "ORDER-12345",
      "total_amount": 99.99
    }
  }'

Responses

successful

Bodyapplication/json
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": "22",
  "type": "Order",
  "custom_attributes": {
    "order_number": "ORDER-12345",
    "total_amount": 99.99
  },
  "external_id": "123",
  "external_created_at": 1392036272,
  "external_updated_at": 1392036272,
  "created_at": 1734537745,
  "updated_at": 1734537745
}