Tags

A tag is your own word for something, put on a verification or on an applicant. It means whatever your team decides it means, we never interpret one, and your applicants never see them.

They exist because the alternative is a free-text note. A note is fine for one case and useless across a thousand: you cannot filter by it, two people write the same thing three ways, and a month later nobody can answer "how many of these did we see". A tag is the same sentence fragment made countable.

They are not a manual-review feature

You can tag any verification, including every one the engine approved or rejected on its own. That is most of them, and it is usually the interesting case: you go back to something that was auto-approved, decide you disagree, and want that recorded somewhere your team will find it.

Tagging during a review is also supported, from the decision screen in your console, and the tags are written in the same transaction as the decision.

Two things you can tag

A verification is one attempt. A tag here describes what happened on that run: manual id check, document from a country we do not usually see.

An applicant is the person, and a tag there is waiting on them the next time they come back: known good, watch this one. Applicant records are created once a face has been matched, so a verification that has just started may not have one yet.

Names are matched loosely on purpose

"High Risk", "high risk" and "high-risk" are the same tag. Each name is reduced to a normalised form, lowercased with runs of anything that is not a letter or digit collapsed to a single hyphen, and two names that reduce to the same thing resolve to the same tag.

That is what keeps a tag filter trustworthy. Without it your list grows a near-duplicate every time somebody types quickly, and no error is ever raised to tell you.

The normalised form is published as slug on the tag, so you can predict it:

{
  "id": "tag_9f2c1a7b40de",
  "object": "tag",
  "name": "High Risk",
  "slug": "high-risk",
  "color": "red",
  "description": "Watch this one. Escalate anything unusual next time"
}

Tag straight from your own rules

You do not have to look a tag up before using it. Send a name and it resolves to the tag you already have, or creates it:

curl -X POST https://api.trustwix.com/v1/verifications/vs_.../tags \
  -H "Authorization: Bearer $TRUSTWIX_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names": ["suspected mule account"]}'

Applying a tag that is already there is a no-op rather than an error, so this is safe to retry.

Reading them back

Every verification carries its tags, with no extra permission and nothing to opt into:

{
  "id": "vs_...",
  "object": "verification",
  "verdict": "approve",
  "tags": [
    { "id": "tag_9f2c1a7b40de", "name": "High Risk", "color": "red" }
  ]
}

tags is always present and is an empty array when nothing is tagged, so you never have to tell "untagged" from "this response does not carry tags".

Retiring a tag does not erase it

Removing a tag from your list stops it being offered on new records. Everything already carrying it keeps showing the label, because a decision you took six months ago has to keep meaning what it meant. The name becomes free to create again afterwards.

Permissions

Reading tags rides on verification:read. Creating, renaming, retiring and applying them need verification:create, the same write capability that starts a verification.

One thing worth knowing before you rename: a rename is retroactive. The new name shows on every verification already carrying that tag, including decisions already sent to your applicants.