Verification Sessions

A session represents one identity verification. Creating it returns a widget_url you deliver to your customer, and a session_id 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 '{
  "user_ref": "user-123",
  "language": "es",
  "delivery": { "mode": "webhook" }
}'

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

Request Fields

Response Fields

Prefill

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

{
  "user_ref": "user-123",
  "prefill": {
    "document_type": "drivers_license",
    "issuing_state": "PA",
    "document_number": "31612967",
    "first_name": "Ana",
    "last_name": "Silva",
    "date_of_birth": "1988-03-04"
  }
}

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

prefill.document_number 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 data_check: true to verify that the document belongs to the person you expected — not just that the document is genuine.

{
  "user_ref": "user-123",
  "data_check": true,
  "prefill": {
    "first_name": "Ana",
    "last_name": "Silva",
    "date_of_birth": "1988-03-04"
  }
}

With data_check: true:

• Extracted data is compared field by field against the prefill payload.
• The result carries prefill_comparison (per-field outcomes, including fuzzy name-match scores) and prefill_mismatches (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. data_check: true without a prefill payload is a 422 — there would be nothing to compare against.

Delivery

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

Requesting webhook mode without a webhook_url 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/{session_id}
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"

{
  "session_id": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "user_ref": "user-123",
  "status": "in_review",
  "step": "done",
  "delivery_mode": "webhook",
  "result": { "…": "the normalized result, updated in place" },
  "created_at": "2026-07-31T14:02:11.481Z",
  "updated_at": "2026-07-31T14:04:57.902Z"
}

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

Validate a Document Number

Endpoint: POST /v1/validators/document-number
Authentication: none required

A stateless format check against the same registry the verification pipeline uses: US driver's-license formats for all 50 states and DC, per-country passport formats, and identity-card formats where the jurisdiction defines one. Nothing is stored and no verification is consumed. Useful for validating input in your own form before creating a session.

curl --request POST \
  --url https://{FQDN}/v1/validators/document-number \
  --header 'Content-Type: application/json' \
  --data '{
  "document_type": "drivers_license",
  "number": "31612967",
  "issuing_state": "PA"
}'

{
  "document_type": "drivers_license",
  "number": "31612967",
  "issuing_state": "PA",
  "valid": true,
  "rule": "us_dl:PA",
  "detail": "document number matches the PA license format"
}

valid is deliberately three-valued:

rule identifies which rule was applied — us_dl:PA, passport:USA, passport:generic, or us_dl:unknown_state when a license was submitted without a resolvable state (which yields valid: null). issuing_state is a US state code or name for driver's licenses, and an ISO 3166-1 alpha-3 country code for passports and identity cards.

Next Steps

• Widget Delivery — getting the customer through the flow
• Receiving Results — webhook and redirect handling
• Tenant Configuration — which document types and jurisdictions you accept