Skip to main content

Tags

A tag is a label a tenant defines and puts on people and on its catalog: atoms, sequences, journeys and public assets. Journeys assign and unassign a person's tags (createUserTag, deleteUserTag) and branch on them (tags.<tag> exists), so a tag is how a journey leaves itself a note.

  • A person's tags are assigned and unassigned one at a time, at /users/{id}/tags.
  • Catalog content's tags are its tagIds. An atom, sequence or journey publishes them with its version; an asset's change at once. Each list filters by them (?tagIds=, any of), and they travel through export and import as @tags/<CODE>.
  • Only the tenant's own tags can be put on its content, and only on public assets.
  • A tag's code and its externalId are each unique in the tenant.
  • A tag can't be deleted while anyone holds it or any content names it (tag_in_use). Archive it instead: it leaves the pickers and stays where it is used.

Tags from an outside system​

A tag's externalId is an outside system's own name for it. An API key whose role holds userTags.writeByExternalId (the API client role does) tags a person by those names:

POST /api/v1/users/{id}/tags
Authorization: Bearer <access token>
Content-Type: application/json

{ "external_ids": ["<external id>", "<external id>"] }

It is all or nothing: if any name matches no tag in the key's tenant, none is applied and the response lists the ones that didn't match. A tag has no external id until one is set on it (createTag or updateTag).