Applicant data

A verdict tells you whether to let someone in. It does not tell you who they are. When you need the name, the date of birth or the document number that the verification actually established, ask for it explicitly when you retrieve the verification.

curl "https://api.trustwix.com/v1/verifications/vs_2f8a1c9b4e7d?include=applicant,documents" \
  -H "Authorization: Bearer TWK_..."

include takes a comma-separated list. applicant adds the identity read from the document, documents adds the captured images, and values we do not recognise are ignored. Ask for only what you will use.

This needs a permission you do not have by default

Both expansions require the applicant:read scope, and that scope is in neither environment's default permission set, on purpose. It is the only scope that returns a real person, so it is granted per key on request rather than inherited by every key you have ever created. Ask us and we enable it on one specific key, which you can then revoke on its own without disturbing the rest of your integration.

Requesting an expansion without the scope returns 403 rather than quietly dropping the field from the response. That is deliberate, and it is the property you want: a missing applicant always means the verification has no applicant data, never that your key was not allowed to see it. You will never silently write an empty name into your own database.

Only read this if you need to store it

Every field here is personal data, and most of it is special-category data under most privacy regimes. If your product only needs to know whether the person passed, use the verdict and do not request the expansion at all. That is the cheapest compliance posture available to you.

The applicant object

{
  "applicant": {
    "object": "applicant_data",
    "fields": {
      "full_name": "Ana Beatriz Silva",
      "date_of_birth": "1991-04-17",
      "nationality": "BRA",
      "document_number": "FX1234567",
      "expiry_date": "2031-04-16"
    }
  }
}

fields is a flat map of name to string value, and every field is optional. This is not hedging: the document decides what exists. A passport carries no licence class, some national cards carry a father's name, and plenty of documents omit a field you might assume is universal. Write your code to handle each field being absent, and never index into this map assuming a key is there.

Common names are full_name, first_name, last_name, date_of_birth, sex, nationality, document_number, personal_number, expiry_date, issue_date, address and email. New names can appear, so treat the map as open.

A name ending in _native carries the same value in the script printed on the document rather than transliterated into Latin characters. If you serve applicants whose documents are in Arabic, Persian, Cyrillic or any non-Latin script, these are the values to show back to the person, and the transliterated form is the one to match against your existing records.

The documents array

{
  "evidence": [
    {
      "id": "ev_3c81f0a2",
      "object": "evidence",
      "kind": "passport",
      "side": null,
      "url": "https://…",
      "url_expires_in": 900,
      "mrz_valid": true,
      "barcode_consistent": null,
      "country": "BRA",
      "captured_at": "2026-07-26T16:30:14.000Z"
    }
  ]
}

Field	Notes
`kind`	`passport`, `id_card`, `drivers_license`, `residence_permit`, `selfie` or `liveness_frame`.
`side`	`front` or `back` on a document with two, `null` otherwise.
`url`	Short-lived download url. See below.
`url_expires_in`	Seconds the url stays valid, counted from when the response was built.
`mrz_valid`	Whether the machine-readable zone checksums passed. `null` means the document has none, which is not a failure.
`barcode_consistent`	Whether the barcode agrees with the printed fields. `null` means there was no barcode to read.
`country`	The issuing country, when we could establish it.

The url expires, and then it goes away

url is presigned and short-lived. Fetch it promptly and store the bytes yourself if you need to keep them, because a url you cached will stop working long before the image does.

url is also null once the image has passed our retention window and been deleted. The evidence record stays, so you keep the fact that a passport was captured and that its MRZ checked out, but the image itself is gone and no call will bring it back. Treat null as final rather than as an error to retry.

A note on where this belongs

The point of the hosted flow is that biometric data never touches your infrastructure. Requesting documents reverses that for the images you fetch: from the moment you download one, it is in your logs, your backups and your compliance scope. Plenty of teams need exactly that, for a regulator or a manual review desk of their own. Just make it a decision rather than a default.