Quickstart

This walkthrough creates a verification, runs it in the sandbox, forces a decision with a magic value, and receives the result on your webhook. Everything here uses a test key, so no real identity data is involved.

Before you start

You need a TrustWix account with console access, a test secret key from the console, and an endpoint that can receive a webhook. A temporary tunnel is fine for local development. Every secret key reads TWK_ followed by one long token, and the console lists which environment each key belongs to.

Keep your secret key on the server

A secret key must never reach the browser. The browser only ever holds the short-lived client_token that the create call returns.

Create a flow

A flow is the named set of checks a user goes through. Create one in the console, or clone a starter template such as document plus liveness, and note its id. Flow ids start with flw_.

You can skip this step for now. If you create a verification without a flow and without inline checks, TrustWix runs the default preset: document, liveness and face match.

Create a verification

From your backend, create a verification bound to the flow and to your own user reference.

Request

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" },
    "locale": "en"
  }'

Response

{
  "id": "vs_2f8a1c9b4e7d",
  "object": "verification",
  "status": "pending",
  "mode": "sandbox",
  "flow": "flw_id_and_liveness",
  "verdict": null,
  "reason_codes": [],
  "checks": [
    { "id": "chk_...", "object": "check", "type": "document", "status": "pending", "verdict": null },
    { "id": "chk_...", "object": "check", "type": "liveness", "status": "pending", "verdict": null },
    { "id": "chk_...", "object": "check", "type": "face_match", "status": "pending", "verdict": null }
  ],
  "client_token": "cts_...",
  "hosted_verify_url": "https://verify.trustwix.com/v/vs_2f8a1c9b4e7d",
  "expires_at": "2026-07-26T17:30:00.000Z",
  "created_at": "2026-07-26T16:30:00.000Z",
  "updated_at": "2026-07-26T16:30:00.000Z"
}

Store the id. It is how you reconcile the result later.

Send the user through the flow

For the hosted path, redirect the user to hosted_verify_url, or send them the link. For the embedded path, pass client_token to the flow running in your own page. The token is scoped to this one verification and expires quickly, so treat it as an opaque string and never parse it.

client_token and hosted_verify_url are returned only on create. They are not repeated when you retrieve the verification later.

Force a decision in the sandbox

The sandbox runs no real checks, so you drive the outcome yourself with a magic applicant value. This is how you test approval and decline handling without uploading anything.

Force an approval

curl https://api.trustwix.com/v1/verifications \
  -H "Authorization: Bearer TWK_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sandbox-user-123-approval-1" \
  -d '{ "applicant": { "reference_id": "approved" } }'

Swap approved for rejected, review or pending to exercise the other branches. See Sandbox and magic values for the full table.

Receive the result

When a verification reaches a terminal state, TrustWix sends verification.completed plus a verdict-specific event to every subscribed endpoint.

POST to your endpoint

{
  "id": "evt_9c2f1b7a",
  "event": "verification.approved",
  "createdAt": "2026-07-26T16:30:25.032Z",
  "data": {
    "sessionId": "vs_2f8a1c9b4e7d",
    "verdict": "approve",
    "status": "approved",
    "reasonCodes": []
  }
}

Verify the signature against the raw request body before you parse it, then reconcile by data.sessionId. The webhook is the source of truth, and the verdict is authoritative only once status is terminal. See Webhooks for signature verification and retries.

Next steps

Authentication covers secret keys and environments in depth. Verdicts explains how per-check results roll up into one decision. Flows shows you how to add the exact checks your product needs. Go live is the checklist before you switch to a live key.