Applicants

An applicant is the person a verification is about. You do not have to create one up front. Passing an applicant object when you create a verification is enough, and TrustWix maintains the record behind it.

{
  "applicant": {
    "reference_id": "your-user-123",
    "email": "ana@example.com"
  }
}

reference_id is your join key

reference_id is your own identifier for the user, up to 200 characters. It is the value you should use to tie a verification back to your database. Use a stable internal id, not something the user can change like an email address or a username.

Store the verification id we return against your user when you create it. That is the join you will actually rely on: reference_id travels with the verification and comes back on every read of it, but it is not a searchable field, so it cannot be used to go looking for a user after the fact. The one identifier you can search on later is the applicant's email, covered in Check existing applicants.

Repeat attempts

A user who fails a verification and tries again produces a second verification with the same reference_id. Each attempt is its own object with its own id, status and verdict. Nothing is overwritten, so you keep a complete audit trail of what was tried and when.

That also means reference_id is not unique across verifications. Reconcile on the verification id, and use reference_id when you want the whole history for one person.

Reading applicants

/v1/applicants lists the applicants on your account and /v1/applicants/{id} retrieves one, both with a key holding verification:read. What comes back is deliberately limited: a public id, timestamps, and whether an identity link exists. Never the identity read off a document, never the captures, and no email address.

That makes it a thin listing rather than a lookup. To go from a person you know to the verifications they ran, use Check existing applicants, which matches on email. To read the identity a verification established, use Applicant data on that verification, which needs a scope granted per key.

Sending the name you already hold

If your signup form collected a name, send it as first_name and last_name. In whatever script you store it in, Persian or Latin or anything else.

{
  "applicant": {
    "reference_id": "your-user-123",
    "first_name": "Sajad",
    "last_name": "Zare"
  }
}

We compare it against the name our reader takes off the document, and if the two describe different people we flag it on the verification. That is how you catch a user who signed up under one name and then verified with somebody else's document. Without it the comparison cannot be made: your copy of the name never reaches us, so the disagreement is invisible on both sides.

The comparison is deliberately forgiving. Spelling differences, letter variants that different keyboards produce, word order, a middle name on one side and not the other, and romanisations that disagree are all treated as the same person. It flags a different name, not a different spelling. Where the two are written in scripts that cannot be compared, no claim is made either way.

Neither field is ever shown to the applicant, and neither is used to prefill the flow. They are evidence to compare against, not values we trust.

Consent

Biometric checks require the user's explicit, informed consent before capture, and the record of that consent has to be attached to the verification rather than kept only in your own system. The hosted flow collects it for you. If you build your own front end, record it through /v1/consent before capture begins.

Data minimisation

Send the least you need. email does two things: it lets TrustWix send the user a link or a reminder, and it is the only identifier you can search verifications by later. If you expect to reconcile a list of your users against us at some point, send it. If you will never need either, leave it out.

Everything you pass in metadata comes back on every read of the verification and is echoed into webhook payloads, so keep personal data out of it. In particular, do not put the applicant's email there to make it searchable. It is not indexed, it is not encrypted, and applicant.email is the supported way to do this.