Verification Sessions

A session represents one identity verification. Creating it returns a widgetUrl you deliver to your customer, and a sessionId you use to correlate the result.

Create a Session

Endpoint: POST /v1/sessions
Authentication: Bearer token with the sessions scope

curl --request POST \
  --url https://{FQDN}/v1/sessions \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "userRef": "user-123",
  "language": "es",
  "delivery": { "mode": "webhook" }
}'

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "status": "pending",
  "widgetUrl": "https://{FQDN}/verify/8Kd2mQ…"
}

Request Fields

Response Fields

Prefill

prefill carries what you already know about the person. It has two distinct effects.

{
  "userRef": "user-123",
  "prefill": {
    "documentType": "drivers_license",
    "issuingState": "PA",
    "documentNumber": "31612967",
    "firstName": "Ana",
    "lastName": "Silva",
    "dateOfBirth": "1988-03-04"
  }
}

Prefill fields other than documentType do not change the decision unless you set dataCheck: true. Without it, the values are carried for comparison and reported in the result, but a mismatch does not route the session anywhere.

prefill.documentNumber is validated at this call, however: a number that violates its jurisdiction's known format is rejected with 422 rather than accepted and failed later. Check a number before you get here with the validator endpoint.

Data Checks

Set dataCheck: true to verify that the document belongs to the person you expected — not just that the document is genuine.

{
  "userRef": "user-123",
  "dataCheck": true,
  "prefill": {
    "firstName": "Ana",
    "lastName": "Silva",
    "dateOfBirth": "1988-03-04"
  }
}

With dataCheck: true:

• Extracted data is compared field by field against the prefill payload.
• The result carries prefillComparison (per-field outcomes, including fuzzy name-match scores) and prefillMismatches (the field names that disagreed).
• A mismatch adds a failing soft check, routing the session to in_review rather than declining it.

Names are compared with fuzzy matching against a configurable similarity threshold, so ordinary spelling and transliteration variance does not create false mismatches. dataCheck: true without a prefill payload is a 422 — there would be nothing to compare against.

Delivery

{ "delivery": { "mode": "redirect", "redirectUrl": "https://you.example/kyc-done" } }

Requesting webhook mode without a webhookUrl configured for your tenant is a 422. See Receiving Results for signature verification in both modes.

Error Responses

All of these return 422 with a detail explaining the specific cause:

Authentication and authorization failures return 401 or 403 — see Authentication.

Retrieve a Session

Endpoint: GET /v1/sessions/{sessionId}
Authentication: Bearer token with the sessions scope

This is the authoritative record of a verification. Poll it when you need a guarantee rather than a push, to reconcile a webhook you may have missed, or to read the outcome of a session that went to manual review.

curl --request GET \
  --url https://{FQDN}/v1/sessions/$SESSION_ID \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "userRef": "user-123",
  "status": "in_review",
  "step": "done",
  "deliveryMode": "webhook",
  "result": { "…": "the normalized result, updated in place" },
  "createdAt": "2026-07-31T14:02:11.481Z",
  "updatedAt": "2026-07-31T14:04:57.902Z"
}

Sessions are strictly tenant-scoped. Another tenant's sessionId returns 404 — never a partial disclosure.

Next Steps

• Document Number Validator — check a number before you get here
• Widget Delivery — getting the customer through the flow
• Receiving Results — webhook and redirect handling