Verifications

A verification is a single session in which one person works through the checks of one flow. It is the object you create, the object the user interacts with, and the object every webhook and every result refers back to. Verification ids start with vs_.

Lifecycle

A verification is created in pending, moves to processing once submissions are in and the checks are running, and settles on one of three terminal states. A session the user never completes settles on expired instead.

pending ──▶ processing ──▶ approved
                       ├─▶ rejected
                       └─▶ manual_review

pending ──▶ expired          (the user never finished in time)

Statuses covers what each one means and which are safe to act on.

Creating one

curl https://api.trustwix.com/v1/verifications \
  -H "Authorization: Bearer TWK_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: user-123-onboarding" \
  -d '{
    "flow": "flw_id_and_liveness",
    "applicant": { "reference_id": "your-user-123", "email": "ana@example.com" },
    "locale": "es",
    "return_url": "https://your-app.example/kyc/done",
    "metadata": { "plan": "pro" }
  }'

Field	Type	Notes
`flow`	string	A saved flow id, starting with `flw_`. Provide this or `checks`, not both.
`checks`	array	An inline list of checks, for one-off compositions.
`locale`	string	BCP-47 language tag for the user-facing flow.
`return_url`	string	Where the hosted flow sends the user when they finish.
`applicant`	object	`reference_id` (your own user id) and `email`.
`metadata`	object	Arbitrary key and value pairs, returned unchanged on every read.

If you send neither flow nor checks, the default preset runs: document, then liveness, then face match.

What you get back

The create response is the only place client_token and hosted_verify_url appear. Store id, hand exactly one of the two credentials to the user-facing surface, and drop the rest.

Field	Notes
`id`	The verification id. Your reconciliation key.
`status`	Lifecycle state, see Statuses.
`mode`	`sandbox` or `live`, derived from the key you used.
`verdict`	`approve`, `reject`, `review`, or `null` until the session settles.
`reason_codes`	Why the verdict is what it is. Empty on a clean approval.
`checks`	One entry per check in the flow, each with its own status and verdict.
`client_token`	Short-lived credential for an embedded flow. Create response only.
`hosted_verify_url`	The hosted page for this session. Create response only.
`expires_at`	When an unfinished session will be marked `expired`.

Reading one back

curl https://api.trustwix.com/v1/verifications/vs_2f8a1c9b4e7d \
  -H "Authorization: Bearer TWK_..."

Polling is supported but it is not how you should build. Subscribe to webhooks and use the retrieve endpoint for reconciliation and support lookups.

Listing

GET /v1/verifications is cursor-paginated and newest first. Pass limit up to 100, starting_after with a verification id to page forward, and status to filter. The response carries has_more and next_cursor.