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
  "session_id": "session_abc123",
4
  "external_ref": "quickstart_user_1",
5
  "status": "approved",
6
  "is_sandbox": true
7
}

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
}

Step 5: Set up a webhook (recommended)

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.