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

Create or update a custom object instance

Creates or updates an instance of a custom object type. Supply external_id to identify the instance in the external system and custom_attributes to set its custom values; the request body is optional.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 4 body fields
custom_object_type_identifierstringrequired
The unique identifier of the custom object type that defines the instance structure.
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

Optional data for creating or updating a custom object instance.

external_idstringoptional
A unique identifier for the Custom Object instance in the external system it originated from.
external_created_atintegeroptional
The time when the Custom Object instance was created in the external system it originated from.
external_updated_atintegeroptional
The time when the Custom Object instance was last updated in the external system it originated from.
custom_attributesobjectoptional
The custom attributes which are set for the Custom Object instance.

3 status codes
200Returns the custom object instance, including its identifiers, timestamps, type, and custom attributes.
idstringoptional
The Intercom defined id representing the custom object instance.
external_idstringoptional
The id you have defined for the custom object instance.
external_created_atintegeroptional
The time when the Custom Object instance was created in the external system it originated from.
external_updated_atintegeroptional
The time when the Custom Object instance was last updated in the external system it originated from.
created_atintegeroptional
The time the attribute was created as a UTC Unix timestamp
updated_atintegeroptional
The time the attribute was last updated as a UTC Unix timestamp
typestringoptional
The identifier of the custom object type that defines the structure of the custom object instance.
custom_attributesobjectoptional
The custom attributes you have set on the custom object instance.
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 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 is not found. The custom_object_type_identifier path parameter must identify the type whose instance you want to create or update; values in custom_attributes must be strings.