Intercom API (unofficial showcase)
POST/tags

Create or apply a tag

Creates or updates a tag, or applies or removes a tag from companies or users. Supply the fields for the operation you want to perform; each operation returns a tag object.

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

1 parameter · 2 body fields
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Supply a payload for the tag operation: create or update a tag, tag or untag companies, or tag users.

namestringrequired
The name of the tag, which will be created if not found, or the new name for the tag if this is an update request. Names are case insensitive.
idstringoptional
The id of tag to updates.

3 status codes
200Returns a tag object and, when applicable, details of the users or companies that were tagged or untagged.
typestringoptional
value is "tag"
idstringoptional
The id of the tag
namestringoptional
The name of the tag
usersarray<object>optional
The users that were tagged or untagged.
companiesarray<object>optional
The companies that were tagged or untagged.
400Returned when the request parameters are invalid.

One documented failure

  • parameter_invalid

    invalid tag parameters

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error 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

Error handling

A 400 is returned when the request parameters or body are invalid; include name for tag creation or update, and include companies when tagging or untagging companies. A 401 is returned when the request is unauthorized. The Intercom-Version header selects the API version and defaults to 2.17 when omitted.