Integration Guides

Web Capture Flow

The web capture flow is Verifa’s hosted verification experience. You create a session, redirect the user to the capture URL, and Verifa handles document scanning, selfie collection, liveness detection, and consent collection.

How it works

Your Server                    Verifa                         User
    │                            │                              │
    │  POST /api/v1/sessions     │                              │
    │───────────────────────────▶│                              │
    │  { capture_url }           │                              │
    │◀───────────────────────────│                              │
    │                            │                              │
    │  redirect to capture_url   │                              │
    │─────────────────────────────────────────────────────────▶│
    │                            │     consent + documents      │
    │                            │◀─────────────────────────────│
    │                            │     selfie + liveness        │
    │                            │◀─────────────────────────────│
    │                            │                              │
    │                            │  redirect to redirect_url    │
    │                            │─────────────────────────────▶│
    │                            │                              │
    │  webhook: session.approved │                              │
    │◀───────────────────────────│                              │

Step 1: Create a session

$curl -X POST https://api.withverifa.com/api/v1/sessions \
>  -H "X-API-Key: vk_live_your_key_here" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "external_ref": "user_abc123",
>    "country": "US",
>    "redirect_url": "https://your-app.com/verify/complete"
>  }'
1{
2  "id": "session_abc123",
3  "status": "pending",
4  "capture_url": "https://app.withverifa.com/verify/tok_abc123...",
5  "qr_code_data_url": "data:image/png;base64,...",
6  "is_sandbox": false,
7  "created_at": "2026-02-01T12:00:00Z",
8  "expires_at": "2026-02-01T12:20:00Z"
9}

Key parameters

ParameterDescription
external_refYour internal user ID. Links the session to an identity record.
countryISO country code. Scopes document type options and geo-dependent checks.
redirect_urlWhere to send the user after capture completes.
workflow_idSpecific workflow to use (defaults to your org’s default workflow).
metadataArbitrary key-value data stored with the session.

Step 2: Send the user to capture

Option A: Full-page redirect

The simplest approach. Redirect the user to the capture_url:

1// After creating a session on your server
2window.location.href = session.capture_url;

After the user completes the flow, they are redirected to your redirect_url with query parameters:

https://your-app.com/verify/complete?session_id=session_abc123&status=completed

Option B: Iframe embed

Embed the capture flow in your page:

1<iframe
2  id="verifa-capture"
3  src="https://app.withverifa.com/verify/tok_abc123..."
4  allow="camera; microphone"
5  style="width: 100%; height: 700px; border: none;"
6></iframe>

Listen for completion via postMessage:

1window.addEventListener("message", (event) => {
2  if (event.origin !== "https://app.withverifa.com") return;
3
4  const { type, session_id, status } = event.data;
5
6  if (type === "verifa:complete") {
7    console.log(`Session ${session_id} completed with status: ${status}`);
8    // Remove iframe and show success state
9  }
10
11  if (type === "verifa:error") {
12    console.error("Capture error:", event.data.error);
13  }
14});

Option C: QR code

Display the qr_code_data_url so mobile users can scan and complete verification on their phone:

1<img src="${session.qr_code_data_url}" alt="Scan to verify" />
2<p>Scan with your phone camera to complete verification</p>

This is useful for desktop-first flows where the user’s phone has a better camera.

Step 3: Capture flow screens

The capture flow guides the user through these screens (order depends on your workflow’s data_requirements):

Biometric processing consent. Records timestamp, IP address, and consent version. Required before any data collection.

2. Document type selection

The user selects their document type:

  • Passport
  • Driver’s license
  • National ID card
  • Residence permit

Available types are scoped by the country parameter.

3. Document upload

Front side (required) and back side (if applicable). The capture UI provides:

  • Real-time camera viewfinder with alignment guides
  • Auto-capture when a document is detected
  • Manual photo option as fallback
  • Image quality feedback (blur, glare, resolution)

Documents are encrypted with AES-256-GCM immediately on upload. Maximum file size: 10 MB.

4. Selfie

Live selfie capture with alignment guide. The selfie is compared against the ID photo for face matching.

5. Liveness challenge

Three randomized challenges from: blink, smile, turn left, turn right, look up, nod, open mouth. Challenges are cryptographically bound to the session via a server-generated nonce to prevent replay attacks.

6. Additional data (optional)

If your workflow requires it:

  • Email and phone — For risk scoring and OTP verification
  • Address — For address validation checks
  • Proof of address — Upload utility bill or bank statement
  • SSN — For US-specific checks

Step 4: Handle the result

Configure a webhook endpoint to receive real-time notifications:

1{
2  "event": "session.approved",
3  "data": {
4    "session_id": "session_abc123",
5    "external_ref": "user_abc123",
6    "status": "approved",
7    "is_sandbox": false
8  },
9  "created_at": "2026-02-01T12:05:00Z"
10}

See Webhooks for setup and signature verification.

Via polling

Poll the session status until it reaches a terminal state:

$curl https://api.withverifa.com/api/v1/sessions/session_abc123 \
>  -H "X-API-Key: vk_live_your_key_here"

Once status is completed, fetch the result:

$curl https://api.withverifa.com/api/v1/sessions/session_abc123/result \
>  -H "X-API-Key: vk_live_your_key_here"

Capture token expiration

The capture URL token expires after 20 minutes by default. If the user doesn’t complete the flow in time, the session status changes to expired.

To re-issue a token for an expired session:

$curl -X POST https://api.withverifa.com/api/v1/sessions/session_abc123/resume \
>  -H "X-API-Key: vk_live_your_key_here"

This returns a new capture_url with a fresh token. Previously uploaded documents are preserved.

Fraud signal collection

The capture flow automatically collects 150+ fraud signals in the background:

  • Behavioral — Completion time, hesitation patterns, copy-paste detection, keystroke dynamics, mouse/touch patterns
  • Device — Browser fingerprint, bot detection, virtual camera detection, WebGL analysis, memory constraints
  • Network — IP consistency, user-agent tracking, timezone validation
  • Document — EXIF metadata analysis, blur/glare detection, screen photo detection, forensic analysis

These signals feed into the risk_assessment check during workflow execution. You don’t need to collect or submit them — the capture flow handles everything.

Theming

Customize the capture flow appearance in the Verifa dashboard under Settings > Organization (Theming section):

  • Primary and accent colors
  • Logo
  • Font family
  • Button styles
  • Background colors

Error handling

If the capture flow encounters an error, the user sees an error screen with a retry option. Common errors:

ErrorCauseResolution
Token expiredUser took too longResume the session to get a new token
Camera deniedUser denied camera permissionPrompt user to allow camera access
Upload failedNetwork error during document uploadAutomatic retry with user prompt
Session not foundInvalid or already-completed tokenCreate a new session