How Verifa Works

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.

1
{
2
  "id": "session_abc123",
3
  "status": "pending",
4
  "capture_url": "https://app.withverifa.com/verify/tok_...",
5
  "expires_at": "2026-02-01T12:20:00Z"
6
}

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:

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:

1
{
2
  "session_id": "session_abc123",
3
  "status": "approved",
4
  "face_match_passed": true,
5
  "face_match_score": 0.94,
6
  "age_check_passed": true,
7
  "extracted_age": 28,
8
  "extracted_data": {
9
    "first_name": "Jane",
10
    "last_name": "Doe",
11
    "date_of_birth": "1997-06-15",
12
    "document_type": "drivers_license",
13
    "document_number": "D12345678",
14
    "document_issuing_state": "CA"
15
  },
16
  "check_results": {
17
    "document_ocr": { "status": "passed" },
18
    "face_match": { "status": "passed", "score": 0.94 },
19
    "watchlist_screening": { "status": "passed", "hits": 0 },
20
    "risk_assessment": { "status": "passed", "risk_score": 12, "risk_level": "low" }
21
  }
22
}

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:

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 — Create your first session in 5 minutes
• Choosing an Integration Method — Pick the right approach for your use case
• Sessions — Deep dive into the session lifecycle

Related

• Workflows — Define and customize verification pipelines
• Webhooks Guide — Real-time event notifications
• Fraud Signals — Risk scoring and signal details