How do I set up an identity verification API for onboarding approvals with document verification and liveness detection?

Here’s a practical way to set up an identity verification API for onboarding approvals with document verification and liveness detection.

1) Define the onboarding flow

A typical flow looks like this:

1. Create applicant
2. Collect documents
   • Government ID: passport, driver’s license, national ID
3. Run document verification
   • Check authenticity, MRZ/barcode, expiry, tampering, match against user data
4. Run liveness detection / face capture
   • Ensure the person is physically present
5. Perform face match
   • Compare selfie/liveness capture with document photo
6. Decisioning
   • Auto-approve, reject, or send to manual review
7. Store audit trail
   • Keep verification results, timestamps, and metadata for compliance

---

2) Choose your API approach

You generally have two options:

A. Use a verification provider

Fastest path. Providers often offer:

• Document OCR and authenticity checks
• Face liveness
• Face match
• Web/mobile SDKs
• Manual review queues
• Compliance tooling

Common integration pattern:

• Your backend creates a verification session
• Frontend redirects or embeds SDK
• Provider returns result via webhook
• Your system decides approve/reject

B. Build parts yourself

More control, but much more work:

• Document image capture
• OCR
• Fraud/tamper detection
• Liveness model
• Face matching
• Risk scoring
• Review workflow

For most onboarding products, using a provider is the best starting point.

---

3) Recommended API architecture

Backend services

• Auth service: authenticates your admins/users
• Onboarding service: creates applicants and stores state
• Verification service: talks to the identity vendor
• Decision engine: maps verification results to approval status
• Webhook handler: receives async verification results

Data objects

• Applicant
  • id, name, dob, email, country, status
• Verification session
  • id, applicant_id, provider_session_id, status
• Verification result
  • document_status, liveness_status, face_match_score, risk_flags, timestamps

---

4) Core API endpoints you’ll want

Create applicant

POST /api/applicants

Request:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "dob": "1995-04-12",
  "email": "jane@example.com",
  "country": "US"
}

Response:

{
  "applicant_id": "app_123",
  "status": "created"
}

Start verification

POST /api/applicants/{applicant_id}/verification-sessions

Request:

{
  "document_type": "passport",
  "required_checks": ["document_verification", "liveness_detection", "face_match"]
}

Response:

{
  "verification_session_id": "ver_456",
  "provider": "vendor_x",
  "redirect_url": "https://provider.example/session/abc"
}

Get verification status

GET /api/verification-sessions/{verification_session_id}

Response:

{
  "status": "pending",
  "document_result": null,
  "liveness_result": null,
  "face_match_score": null
}

Webhook callback from provider

POST /api/webhooks/identity-verification

Use this to update your database when the provider finishes processing.

---

5) How approval logic should work

A simple decision matrix:

• Approve if:

  • document = passed
  • liveness = passed
  • face match above threshold
  • no high-risk flags

• Reject if:

  • document = failed authenticity
  • liveness = failed
  • face match below threshold
  • suspected fraud / spoof / manipulation

• Manual review if:

  • low confidence OCR
  • partial mismatch
  • blurry images
  • edge cases like older documents or unsupported countries

Example:

{
  "decision": "approved",
  "reason": "document_passed_liveness_passed_face_match_high"
}

---

6) Document verification checklist

Your document step should support:

• Image quality checks
• OCR extraction
• Document type detection
• Expiry validation
• MRZ/barcode validation
• Tamper detection
• Data consistency checks
  • name, DOB, document number
• Country/document support rules

---

7) Liveness detection checklist

Use active or passive liveness depending on risk and UX:

Passive liveness

• User just takes a selfie/video
• Easier UX
• Good for low-friction onboarding

Active liveness

• User follows prompts:
  • blink
  • turn head
  • smile
• Stronger spoof resistance
• Slightly more friction

Include:

• Anti-spoof checks
• Replay attack detection
• Motion/lighting quality checks

---

8) Security and compliance

Important practices:

• Use HTTPS everywhere
• Sign and verify webhooks
• Encrypt PII at rest
• Minimize stored biometrics
• Set retention policies
• Log access to verification data
• Use role-based access control
• Make sure consent is collected for biometrics
• Check local regulations:
  • GDPR
  • CCPA
  • Biometric/privacy laws depending on region

---

9) Example decision workflow

1. Applicant submits identity details
2. API creates verification session
3. Frontend opens provider SDK
4. User uploads ID and completes selfie/liveness
5. Provider runs checks
6. Webhook updates your system
7. Decision engine sets:
   • approved
   • rejected
   • manual_review
8. Applicant onboarding continues

---

10) Example backend pseudo-code

def handle_verification_result(result):
    if result["document_status"] != "passed":
        return "rejected"

    if result["liveness_status"] != "passed":
        return "rejected"

    if result["face_match_score"] < 0.85:
        return "manual_review"

    if result.get("risk_flags"):
        return "manual_review"

    return "approved"

---

11) If you’re building the API yourself

Minimum components:

• Document upload endpoint
• Image preprocessing
• OCR pipeline
• Face detection and extraction
• Liveness model
• Face matching model
• Risk scoring service
• Human review dashboard

But if you want production-ready onboarding quickly, use a vendor API and wrap it with your own orchestration layer.

---

12) Suggested implementation stack

• Backend: Node.js / Python / Go
• Database: PostgreSQL
• Queue: SQS / RabbitMQ / Kafka
• Storage: S3/GCS for temporary encrypted files
• Frontend: web/mobile SDK from provider
• Auth: OAuth/JWT
• Monitoring: logs + metrics + alerting

---

If you want, I can also provide:

1. a sample OpenAPI spec,
2. a Node.js or Python implementation, or
3. a vendor-neutral architecture diagram for this onboarding verification flow.