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, and it is what lets you find every attempt one user has made. Use a stable internal id, not something the user can change like an email address or a username.

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 secret key scoped for it. What comes back is deliberately limited to what you need to operate: identifiers, timestamps and links to verifications, not the raw captures.

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 is useful when you want TrustWix to be able to send the user a link or a reminder. If you do not need that, leave it out. Everything you pass in metadata comes back on every read of the verification, so keep personal data out of it.