← Back to Blog Developer Guide March 13, 2026 · 10 min read

How to Add Identity Verification to Your App with an API

How do you add identity verification to an app?

Create a verification session through the provider's API, hand the user a hosted or embedded flow to capture their ID and a selfie, then receive the outcome on a webhook rather than polling for it. Your code owns the decision — approve, decline, or route to manual review — keyed on the returned risk score.

At some point, almost every application that handles money, sensitive data, or regulated activities needs to answer one question: is this user who they claim to be?

Regulatory frameworks like KYC (Know Your Customer) and AML (Anti-Money Laundering) require businesses to verify the identity of their users before granting access to certain services. But compliance is only half the story. Identity verification also protects your platform from fraud, reduces chargebacks, and builds trust with legitimate users who want to know that the people they are transacting with are real.

The fastest way to add identity verification to your app is through a dedicated API. This guide walks through how identity verification APIs work, what to look for in a provider, and how to integrate one into your application step by step.

What an Identity Verification API Does

An identity verification API automates the process of confirming a user's identity using their government-issued documents and biometric data. Under the hood, a modern verification API handles several distinct tasks:

• Document OCR and classification — The API accepts an image of an ID document (passport, driver's license, national ID card) and uses optical character recognition to extract fields like name, date of birth, document number, and expiration date. It also classifies the document type and issuing country automatically.
• Document authenticity checks — The extracted document is analyzed for signs of tampering: font inconsistencies, misaligned security features, irregular MRZ (machine-readable zone) checksums, and digital manipulation artifacts.
• Biometric face matching — The user takes a selfie, and the API compares the face in the selfie against the photo on the document. This confirms that the person submitting the document is the same person pictured on it.
• Liveness detection — To prevent spoofing with a printed photo or screen replay, liveness detection analyzes the selfie capture for signs of a real, physically present person. Modern implementations use passive liveness (analyzing a single frame for depth cues, texture, and reflection patterns) rather than asking users to blink or turn their head.
• Data extraction and normalization — The API returns structured data (full name, date of birth, address, document number) in a consistent format regardless of the document type or country of origin.

From your perspective as a developer, all of this complexity is behind a single API. You send images in, you get structured results back.

Build vs. Buy

If you have ever considered building identity verification in-house, here is a candid assessment of what that entails:

• Document coverage — There are over 6,000 government-issued document types across 200+ countries. Each has different layouts, security features, and fonts. Supporting even the top 20 countries requires training or fine-tuning OCR models on hundreds of document templates.
• ML model maintenance — Document fraud techniques evolve constantly. The models you train today will degrade over time as fraudsters adapt. You need a pipeline for collecting new fraud samples, retraining models, and deploying updates without introducing regressions.
• Biometric accuracy — Face matching and liveness detection are their own specialties. Achieving production-grade accuracy across skin tones, lighting conditions, and camera quality requires massive, diverse training datasets and ongoing bias testing.
• Compliance and certification — Regulators and enterprise customers increasingly expect identity verification systems to hold certifications like ISO 30107-3 (liveness detection) and SOC 2. Achieving these takes months and ongoing investment.

For all but the largest companies with dedicated identity teams, using an API is the right call. It lets you ship in days instead of quarters, and you benefit from the provider's ongoing investment in document coverage and fraud detection.

Key Features to Look For

Not all identity verification APIs are created equal. Here are the features that matter most when evaluating providers:

Document and country coverage

Check which document types and countries the provider supports. If your users are primarily in one region, ensure that region's documents are well-supported. If you serve a global audience, look for broad coverage with the ability to add new documents without code changes.

Biometric matching and liveness

Look for providers that offer passive liveness detection (no user actions required) and high-accuracy face matching. Ask about their false acceptance rate (FAR) and false rejection rate (FRR). Good providers publish these numbers.

Fraud signals beyond documents

The best APIs go beyond document and face checks. Look for device fingerprinting, IP risk assessment, behavioral signals (how the user interacts with the capture flow), and repeat fraud detection (has this document or face been seen before in a fraudulent context?).

Webhook support

Verification is inherently asynchronous. The API should notify your backend via webhooks when a verification completes rather than requiring you to poll. Look for signed webhooks with retry logic.

Sandbox and testing

A good sandbox environment lets you test the full verification flow without using real documents. This is critical for development, CI/CD pipelines, and QA. Avoid providers where testing requires real credentials or has usage limits that slow down development.

Compliance certifications

Depending on your industry, you may need your provider to hold SOC 2 Type II, ISO 27001, GDPR compliance attestation, or liveness certification (ISO 30107-3). Check what certifications the provider has and what their data processing agreement covers.

Integration Architecture

Most identity verification APIs follow a similar integration pattern. Here is the typical flow:

1. Create a verification session — Your backend calls the API to create a new session. You pass in configuration (which checks to run, redirect URLs, metadata about the user) and receive a session ID and a capture URL.
2. Redirect the user to capture — You redirect the user to the capture URL (or embed it in an iframe or webview). The provider's capture UI guides the user through photographing their document and taking a selfie. This UI is hosted by the provider and handles camera access, image quality validation, and upload.
3. Processing — Once the user completes capture, the provider processes the images: OCR, document authentication, face matching, liveness detection. This typically takes 5-30 seconds.
4. Webhook callback — When processing completes, the provider sends a webhook to your backend with the session ID and the verification result.
5. Retrieve results — Your webhook handler calls the API to retrieve the full verification results, including extracted data, individual check outcomes, and confidence scores.
6. Act on the result — Based on the outcome (pass, fail, or needs review), your application updates the user's status accordingly.

This architecture is deliberate. By offloading capture and processing to the provider, you avoid handling raw biometric images on your own servers, which simplifies your compliance posture significantly.

Code Example

Here is what the integration looks like in practice. The following examples use curl to illustrate the API calls, but the same pattern applies in any language.

Step 1: Create a verification session

curl -X POST https://api.example.com/v1/sessions \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "standard_kyc",
    "redirect_url": "https://yourapp.com/verification-complete",
    "webhook_url": "https://yourapp.com/api/webhooks/verification",
    "metadata": {
      "user_id": "usr_abc123"
    }
  }'

The response includes a session ID and a capture URL:

{
  "id": "ses_7f2a9b4e",
  "status": "pending",
  "capture_url": "https://capture.example.com/v/ses_7f2a9b4e",
  "expires_at": "2026-03-13T15:30:00Z"
}

Redirect your user to capture_url. They will photograph their document and take a selfie using the provider's capture UI.

Step 2: Receive the webhook

When processing finishes, the provider sends a POST request to your webhook_url:

{
  "event": "session.completed",
  "session_id": "ses_7f2a9b4e",
  "result": "passed",
  "timestamp": "2026-03-13T15:28:42Z"
}

Step 3: Retrieve the full results

curl https://api.example.com/v1/sessions/ses_7f2a9b4e/results \
  -H "X-API-Key: your_api_key"

The response contains everything you need:

{
  "session_id": "ses_7f2a9b4e",
  "status": "completed",
  "result": "passed",
  "checks": {
    "document": {
      "result": "passed",
      "document_type": "passport",
      "issuing_country": "US"
    },
    "face_match": {
      "result": "passed",
      "confidence": 0.97
    },
    "liveness": {
      "result": "passed",
      "confidence": 0.99
    }
  },
  "extracted_data": {
    "full_name": "Jane A. Doe",
    "date_of_birth": "1990-04-12",
    "document_number": "X12345678",
    "expiration_date": "2031-04-11"
  },
  "metadata": {
    "user_id": "usr_abc123"
  }
}

Handling Verification Results

A verification result typically falls into one of three outcomes. Your application should handle each differently:

Passed

All checks cleared. The document is authentic, the face matches, and liveness was confirmed. Update the user's status in your database, grant access to the feature or service that required verification, and store the session ID for your records. You generally do not need to store the extracted data yourself unless your compliance requirements demand it.

Failed

One or more checks did not pass. Common reasons include an expired document, a face that does not match the document photo, a failed liveness check (possible spoofing attempt), or a document flagged as fraudulent. In most cases, you should notify the user and offer them the option to retry with a different document. Set a reasonable retry limit (2-3 attempts) to prevent abuse.

Needs review

Some results are ambiguous. The face match confidence might be below the auto-approve threshold but above the auto-reject threshold, or the document might have minor quality issues. These cases should be routed to a human reviewer in your team. A good verification API gives you configurable thresholds so you can tune the balance between automation and manual review based on your risk tolerance.

For each outcome, log the session ID and result for audit purposes. Most regulatory frameworks require you to maintain records of identity verification attempts for a defined retention period.

Testing and Going Live

A smooth path from development to production is one of the most underrated aspects of choosing a verification provider. Here is what a good testing workflow looks like:

Sandbox development

Start in sandbox mode. A well-designed sandbox accepts test documents and returns deterministic results so you can build and test your integration without real PII. Your sandbox should let you simulate all three outcomes (pass, fail, review) so you can verify that your application handles each correctly.

Automated testing

Write integration tests that exercise the full flow: create a session, simulate completion via the sandbox, receive the webhook, and verify that your application state updates correctly. These tests should run in your CI pipeline on every deploy.

Staging with real documents

Before going live, run a small number of real verifications in a staging environment. Use your own documents or those of willing team members. This catches issues that sandbox testing cannot, like camera quality problems on specific devices or unexpected document layouts.

Production rollout

Roll out gradually. Start by requiring verification for new signups only, then backfill existing users. Monitor your pass rates, average processing times, and webhook delivery reliability. If your pass rate is significantly lower than expected, check whether the issue is with document quality (user-side) or verification accuracy (provider-side).

Platforms like Verifa provide separate API keys for sandbox and production, so switching environments is a one-line configuration change with no code modifications required.

Wrapping Up

Adding identity verification to your app is a solved problem at the API level. The integration pattern is straightforward: create a session, redirect the user to a hosted capture flow, listen for a webhook, and act on the result. The complexity that matters — document coverage, fraud detection, biometric accuracy — is handled by the provider.

The key decisions on your side are choosing a provider that fits your coverage and compliance needs, designing your application flow to handle all three outcomes gracefully, and building a testing pipeline that gives you confidence in your integration before real users hit it.

If you are evaluating providers, Verifa offers a generous free tier with full sandbox access, so you can build and test your integration end to end before committing. The API follows the exact patterns described in this guide, and you can be up and running in an afternoon.

For a fuller integration plan — sandbox setup, webhook retries, decision logic and the go-live checklist — see how to integrate a KYC API. Liveness detection explains the anti-spoofing step in the flow above, and what is KYC? covers what regulators expect the API to prove. If your team runs a review queue, the Verifa MCP server puts it in front of an AI assistant.