What this endpoint does

Replaces the full set of tags on a single entity within a list. This is a replace operation, not an append — the tags array you send becomes the entity's complete tag set, removing any previously applied tags not included in the request. Obtain a listId (format report:XXXXX) from Lists: Search. The entity must already be a member of the list — use Lists: Add Entity first if needed. Tags are drawn from a fixed set of predefined values — see Lists: Available Tags for the complete list. Tag updates are currently supported only on company-type lists (Third-Parties Watch List); other list types return 403 — Tag updates are not enabled for this list type. Sending an empty tags array ([]) clears all tags from the entity.

To discover the entity ID needed for this request, first call Lists: Get Entities with Tags to retrieve the entity objects in the list, then use the id field from each entity's object.

Response data

Returns the entity ID and an operation summary. When the tags change, status is tags_updated with tags_before, tags_after, tags_added, tags_removed, and an updated timestamp. When the submitted tags already match the current set, status is tags_unchanged with current_tags reflecting the existing values. This is also the only way to read an entity's current tags — the Lists: Get Entities endpoint does not include tag data in its response.

200Tags successfully updated or unchanged

400Invalid request — invalid tag name, invalid entity, or list not found

403Forbidden — tag updates are not enabled for this list type

404Entity not found on list