How a verification session runs, end to end

Session creation

Your backend opens a verification session. The tenant API key is used only in this call and never reaches the browser. The returned session_id is the only user identifier exposed externally.

POST /v1/sessions · X-Api-Key · state: created

Checks that run at this step

• Velocity limit: at most 5 sessions per applicant per 24 hours
• Velocity limit: at most 20 sessions per IP per 24 hours
• Tenant balance check on production sessions
• Reusable KYC: an approved verification newer than 180 days with no AML alert skips re-verification

Opening the flow

The user opens the WebSDK (iframe) or a mobile SDK. Instead of an API key, the SDK works with a short-lived JWT scoped to that session, valid for 15 minutes by default. Tenant theme and the user's language (54 languages) are applied at this step.

GET /v1/sessions/{id}/config · short-lived JWT (15 min) · CORS allowlist

Checks that run at this step

• Session validity window: 60 minutes (it moves to expired past that)
• Per-tenant CORS allowlist — the SDK only loads from declared origins
• Active modules (document / liveness) are read from the session config

Document selection and capture

The user picks a document type and captures it with the camera. Card edges are detected and cropped automatically; overly blurry or dark frames are flagged on-device and re-captured before ever reaching the server. On the NFC path the MRZ is scanned first — the key that unlocks the chip is derived from it.

POST /v1/sessions/{id}/access-keys · POST /{id}/documents/images

Checks that run at this step

• Passports and MRZ ID cards from any country; documents without an MRZ are read and checked too
• The back side is mandatory where the profile requires it (TD1 MRZ sits on the back)
• On-device quality gates: sharpness, brightness, framing

Document analysis

The session moves to document_processing and a background worker analyzes the images: field reading with our in-house OCR model, MRZ decoding via a separate path calibrated for OCR-B, ICAO 9303 check digit validation, and tamper detection via ELA and texture analysis. Each check produces a 0–100 score, reduced to a single document score by the profile weights.

state: document_processing → liveness_pending | review | rejected

Checks that run at this step

• 15 scored checks, weighted per document type
• 4 unweighted hard rules: document presence, file integrity, document expiry, specimen detection
• Cross-field consistency between front and back (MRZ ↔ printed fields)

Chip reading and passive authentication

On eMRTD-compliant documents the chip is accessed over a BAC-established encrypted channel (Secure Messaging); data groups DG1 (MRZ), DG11 and DG12 are read. ICAO 9303 Passive Authentication proves two things: the hashes in the SOD show the data is unaltered, and the Document Signer certificate shows the data was genuinely written by the issuing state.

POST /{id}/documents/nfc · state: nfc_processing → liveness_pending | review

Checks that run at this step

• SOD hash integrity — verified separately for each data group
• Document Signer certificate signature, validated against the CSCA trust chain
• Chip values are compared to the declared document number / date of birth / expiry — a mismatch goes to manual review (the chip is authoritative)

AML / sanctions screening

The name extracted from the document is screened against open sanctions and PEP lists synced daily. Names are normalized (accents and special characters folded), records with a fuzzy match score of 90% or above become candidates, and candidates whose birth year conflicts are eliminated.

rapidfuzz token_sort_ratio ≥ 90% · match → state: review

Checks that run at this step

• OFAC SDN (U.S. Treasury), UN Consolidated, EU FSF and UK Sanctions List (FCDO) lists
• False-positive elimination via birth-year conflict checks
• A match never auto-rejects — the decision is left to a human

Liveness detection and face matching

The server generates a random sequence of 3–4 challenges (at least one blink and one head movement are guaranteed) alongside a single-use identifier. The user submits one frame per challenge plus a selfie; the server verifies each frame independently against its challenge type, then biometrically compares the selfie to the document photo.

POST /{id}/liveness/start → /{id}/liveness/submit · challenge TTL 300 s

Checks that run at this step

• Every active challenge must pass — no tolerance
• Frame-to-frame consistency: same person, and no static replay
• Passive anti-spoofing (in-house model) + heuristic LBP/FFT/YCrCb signals
• Document photo vs selfie comparison with our in-house face model
• Each approved face is written to pgvector; the same face under a different identity raises a duplicate signal

Decision and delivery

The outcome of every layer is reduced to a single terminal state. Whatever the decision, each state transition is written to a timestamped event log. The result is delivered to your system via an HMAC-SHA256 signed webhook, and can always be read back from the result endpoint.

webhook · X-Signature: sha256=… · GET /v1/sessions/{id}

Checks that run at this step

• Final statuses: approved, declined, expired, abandoned; in_review awaits an analyst and does not expire
• A rejected step keeps the session in_progress and grants the user 3 retry attempts; once they run out it is declined
• Failed webhook deliveries are retried; delivery records are retained
• Personal data is deleted automatically 90 days after the terminal state

not_started

Not Started

Session opened; the user has not opened the link yet.

in_progress

In Progress

The user is going through the steps. A rejected step stays here while retries remain.

resubmitted

Resubmitted

An analyst asked for some steps to be redone; the user has not finished yet.

in_review

In Review

No automatic decision; awaiting an analyst. Does not expire.

approved

Approved

All checks passed — identity verified.

kyc_expired

Kyc Expired

The approval is older than 365 days; request re-verification.

declined

Declined

Final decline: an analyst declined, retries ran out, or time ran out with retries left.

expired

Expired

60 minutes passed before the user started.

abandoned

Abandoned

The user started but did not finish within 60 minutes.