Getting Started

Quickstart

This guide walks you through creating a verification session, completing the capture flow in sandbox, and retrieving the result.

Prerequisites

  • A Verifa account (sign up)
  • A sandbox API key (starts with vk_sandbox_)

You can find your API keys in the Verifa dashboard under Developers > API Keys.

Step 1: Create a session

$curl -X POST https://api.withverifa.com/api/v1/sessions \
>  -H "X-API-Key: vk_sandbox_your_key_here" \
>  -H "Content-Type: application/json" \
>  -d '{"external_ref": "quickstart_user_1"}'

Response:

1{
2  "id": "session_abc123",
3  "status": "pending",
4  "capture_url": "https://app.withverifa.com/verify/tok_...",
5  "qr_code_data_url": "data:image/png;base64,...",
6  "is_sandbox": true,
7  "created_at": "2026-02-01T12:00:00Z",
8  "expires_at": "2026-02-01T12:20:00Z"
9}

Step 2: Complete the capture flow

Open the capture_url in your browser. In sandbox mode, the capture flow lets you:

  1. Give consent
  2. Select a document type
  3. Upload any image as the ID document (sandbox skips real OCR)
  4. Upload any image as the selfie
  5. Choose a sandbox outcome (approve, reject, or needs review)

Step 3: Receive the webhook

If you have a webhook endpoint configured, you’ll receive a session.approved event:

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

No webhook configured yet? Skip to step 4 — you can always poll.

Step 4: Retrieve the result

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

Check the status field. Once it’s completed, fetch the full result:

$curl https://api.withverifa.com/api/v1/sessions/session_abc123/result \
>  -H "X-API-Key: vk_sandbox_your_key_here"
1{
2  "session_id": "session_abc123",
3  "status": "approved",
4  "is_sandbox": true,
5  "face_match_passed": true,
6  "face_match_score": 0.95,
7  "age_check_passed": true,
8  "extracted_age": 28,
9  "extracted_data": {
10    "first_name": "Jane",
11    "last_name": "Doe",
12    "date_of_birth": "1997-06-15",
13    "document_type": "drivers_license",
14    "document_issuing_state": "CA"
15  },
16  "processing_mode": "automatic",
17  "country_used": "US",
18  "created_at": "2026-02-01T12:05:00Z"
19}

Webhooks are the best way to get notified when verifications complete. In the dashboard, go to Developers > Webhooks and add your endpoint URL.

You can also create webhooks via the API:

$curl -X POST https://api.withverifa.com/api/v1/webhooks/endpoints \
>  -H "X-API-Key: vk_sandbox_your_key_here" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "url": "https://your-app.com/webhooks/verifa",
>    "enabled_events": ["session.approved", "session.declined", "session.requires-review"]
>  }'

The response includes a secret for HMAC signature verification. Store it securely.

What’s next

You’ve created a session, completed verification, and retrieved the result. Here’s where to go from here:

  • How Verifa Works — Understand the full architecture
  • Webhooks — Set up real-time notifications with signature verification
  • Workflows — Customize your verification pipeline
  • Sessions — Explore the full session lifecycle and API
  • Testing — Learn how to test with sandbox

Add a “Verify” button with verifa.js

Want a popup or modal instead of a full-page redirect? Use the verifa.js SDK. Your backend creates the session (keeping the API key secure), and the SDK handles the frontend capture experience.

1<script src="https://app.withverifa.com/static/verifa.js"></script>
2<script>
3  document.getElementById('verify-btn').addEventListener('click', async function() {
4    // Your backend creates the session and returns the capture_url
5    const res = await fetch('/api/create-verification', { method: 'POST' });
6    const session = await res.json();
7
8    Verifa.open({
9      captureUrl: session.capture_url,
10      sessionId: session.id,
11      mode: 'popup', // or 'modal'
12      onComplete: function(data) {
13        console.log('Verification complete:', data.sessionId);
14      }
15    });
16  });
17</script>

See the full JavaScript SDK guide for framework examples, display modes, and error handling.