> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.withverifa.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server. # How Verifa Works > Understand the architecture and verification flow behind Verifa. Verifa is a programmable identity verification platform. You define verification workflows, your users complete them through a capture experience, and Verifa returns structured results with extracted data, biometric scores, and fraud signals. ## Architecture overview Verifa is built around five core concepts: ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Session │────▶│ Capture │────▶│ Workflow │ │ (created) │ │ (user UX) │ │ (engine) │ └─────────────┘ └─────────────┘ └──────┬──────┘ │ ┌──────────┴──────────┐ ▼ ▼ ┌──────────┐ ┌──────────┐ │ Result │ │ Review │ │ (auto) │ │ Case │ └──────────┘ └──────────┘ ``` 1. **Session** — A verification request. Your server creates a session via the API, and receives a `capture_url` to send the user to. 2. **Capture** — The user-facing experience. Verifa handles document scanning, selfie collection, liveness detection, and consent — either through the hosted web capture or a mobile SDK. 3. **Workflow** — A directed graph of verification steps. The workflow engine executes checks in sequence — OCR extraction, face matching, age verification, watchlist screening, fraud scoring — and routes to a terminal outcome. 4. **Result** — The structured output of a completed workflow. Contains extracted PII, biometric scores, check outcomes, and a final decision (approved, rejected, or needs review). 5. **Review Case** — When a session requires human judgment, Verifa creates a review case in the queue. Reviewers can approve, reject, or escalate cases through the dashboard or API. ## The verification flow ### Step 1: Create a session Your server sends a `POST /api/v1/sessions` request with an optional `external_ref` (your user ID), country code, and workflow selection. Verifa returns a session object with a `capture_url`. ```json { "id": "session_abc123", "status": "pending", "capture_url": "https://app.withverifa.com/verify/tok_...", "expires_at": "2026-02-01T12:20:00Z" } ``` ### Step 2: User completes capture Redirect (or embed) the user at the `capture_url`. The capture flow guides them through: 1. **Consent** — Biometric processing consent with timestamp and IP recording. 2. **Document selection** — Choose document type (passport, driver's license, national ID, etc.). 3. **Document upload** — Photograph the front (and back, if applicable) of their ID. Images are encrypted at rest immediately. 4. **Selfie** — Take a live selfie for biometric face matching. 5. **Liveness** — Complete a randomized liveness challenge (blink, smile, head turn) to prove physical presence. 6. **Additional data** — Optionally provide email, phone, address, or proof of address documents. The session status transitions from `pending` to `capturing` as the user progresses. ### Step 3: Workflow execution Once the user completes capture, the session moves to `processing` and the workflow engine takes over. A typical workflow executes: | Step | Check | What it does | | ---- | ------------------- | ------------------------------------------------------------- | | 1 | Document OCR | Extracts name, DOB, address, document number from ID images | | 2 | Face match | Compares selfie against the ID photo using ArcFace embeddings | | 3 | Liveness | Validates the liveness challenge responses | | 4 | Age verification | Confirms the user meets the minimum age requirement | | 5 | Document expiration | Rejects expired documents | | 6 | Watchlist screening | Checks against OFAC, EU, UN, and UK sanctions lists | | 7 | Duplicate detection | Searches for the same person under different references | | 8 | Risk assessment | Aggregates 150+ fraud signals into a composite risk score | | 9 | Auto-approve | Routes to approved, rejected, or needs review | Each step produces an independent result. If a step fails, the workflow routes based on your configured graph — to a rejection terminal, a review queue, or an alternative check path. ### Step 4: Receive the result Verifa delivers results through two channels: * **Webhooks** — A `session.approved` or `session.declined` event is sent to your configured endpoint in real time. * **API polling** — Call `GET /api/v1/sessions/{id}` to check the session status, then `GET /api/v1/sessions/{id}/result` for the full result. The result contains: ```json { "session_id": "session_abc123", "status": "approved", "face_match_passed": true, "face_match_score": 0.94, "age_check_passed": true, "extracted_age": 28, "extracted_data": { "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1997-06-15", "document_type": "drivers_license", "document_number": "D12345678", "document_issuing_state": "CA" }, "check_results": { "document_ocr": { "status": "passed" }, "face_match": { "status": "passed", "score": 0.94 }, "watchlist_screening": { "status": "passed", "hits": 0 }, "risk_assessment": { "status": "passed", "risk_score": 12, "risk_level": "low" } } } ``` ### Step 5: Manual review (when needed) If the workflow routes to `needs_review`, a review case is created. Your team can: * **Claim** the case from the queue * **View** extracted data, documents, check results, and fraud signals * **Approve** or **reject** with a reason * **Escalate** to a senior reviewer for dual-review workflows The final decision updates the session result and fires a webhook. ## Identities When a session completes with an `external_ref`, Verifa upserts a persistent **Identity** record. Identities aggregate all verification sessions for a single person, enabling: * Reverification without starting from scratch * Cross-session duplicate detection * Continuous AML monitoring tied to a person, not a session * GDPR right-to-deletion across all sessions for an identity ## Environments Verifa provides two fully isolated environments: | Environment | Purpose | Data | | -------------- | ------------------------------- | ---------------------------------------------- | | **Sandbox** | Build and test your integration | Simulated results, no real document processing | | **Production** | Live verifications | Real document processing, billed usage | Sandbox sessions return simulated results that you can control through the capture UI or API. API keys, webhooks, and workflows are scoped to their environment — sandbox data never mixes with production. ## Security model * **Encryption at rest** — All PII and documents are encrypted with AES-256-GCM using per-session encryption contexts. * **Encryption in transit** — All API communication requires TLS 1.2+. * **HMAC-signed URLs** — Document image URLs are time-limited and cryptographically signed. * **Audit logging** — Every API call and admin action is recorded in a tamper-evident, hash-chained audit log. * **RBAC** — Fine-grained role-based access control for dashboard users and API key scopes. ## Next steps * [Quickstart](/getting-started/quickstart) — Create your first session in 5 minutes * [Choosing an Integration Method](/getting-started/choosing-an-integration-method) — Pick the right approach for your use case * [Sessions](/core-concepts/sessions) — Deep dive into the session lifecycle ## Related * [Workflows](/core-concepts/workflows) — Define and customize verification pipelines * [Webhooks Guide](/integration-guides/webhooks-guide) — Real-time event notifications * [Fraud Signals](/best-practices/fraud-signals) — Risk scoring and signal details