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".

Tag changes reach your own systems

Putting a tag on a verification fires verification.tag_added, and taking one off fires verification.tag_removed, so a conclusion your team records in the console does not stay in the console. The payload names the tag and says whether a person or your own backend applied it, which is what stops your integration from reacting to its own writes. Shapes and the subscription details are in Webhook events. Tagging an applicant fires nothing, because an applicant belongs to no environment and no endpoint can honestly claim it.

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.

On this page