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.

Every prefill field is a string of at most 255 characters. Send a field only when you have a value for it: a blank or whitespace-only value is rejected rather than ignored, so that a field you did not supply is never reported as one the document disagreed with.

{
  "userRef": "user-123",
  "prefill": {
    "documentType": "drivers_license",
    "issuingCountry": "USA",
    "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 a rule can refute — a failed check digit, or a value no jurisdiction could issue — is rejected with 422 rather than accepted and failed later. A number that merely matches none of the shapes we hold for its jurisdiction is not refused; it is carried, and the result reports document_number_valid as undetermined. Check a number before you get here with the validator endpoint, which answers with the same three-valued verdict.

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 document_data_match check and is reported on the result.

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 errorCode: "validation_error"; errors[] names the field and the 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 widget session. Read it when you need a guarantee rather than a push, to recover a webhook you may have missed, or to read the outcome of a session that went to manual review.

A verification created with POST /v1/verifications is not served here — it has a read of its own at GET /v1/verifications/{verificationId}, reachable with the verifications scope. Passing one here returns 404.

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": "completed",
  "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
• Sandbox & Test Data — reserved document numbers that dictate a whole verification outcome