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. Signed in? The dashboard’s Quickstart page pre-fills these snippets with your own key for the environment you’re in.

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:

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

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:

{
  "event": "session.approved",
  "created_at": "2026-02-01T12:05:00Z",
  "idempotency_key": "idk_a1b2c3d4e5f6...",
  "data": {
    "session_id": "session_abc123",
    "external_ref": "quickstart_user_1",
    "status": "approved",
    "is_sandbox": true
  }
}

Route on event, then read the resource fields from data. 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"

{
  "session_id": "session_abc123",
  "status": "approved",
  "is_sandbox": true,
  "face_match_passed": true,
  "face_match_score": 0.95,
  "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_issuing_state": "CA"
  },
  "processing_mode": "automatic",
  "country_used": "US",
  "created_at": "2026-02-01T12:05:00Z"
}

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.

<script src="https://app.withverifa.com/static/verifa.js"></script>
<script>
  document.getElementById('verify-btn').addEventListener('click', async function() {
    // Your backend creates the session and returns the capture_url
    const res = await fetch('/api/create-verification', { method: 'POST' });
    const session = await res.json();
    Verifa.open({
      captureUrl: session.capture_url,
      sessionId: session.id,
      mode: 'popup', // or 'modal'
      onComplete: function(data) {
        console.log('Verification complete:', data.sessionId);
      }
    });
  });
</script>

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