Dashboard

VerifyHuman API Documentation

Complete REST API reference for integrating all VerifyHuman verification products into your applications.

Last Updated: January 5, 2026
API Version: 2.1.0

Table of Contents

Environments

VerifyHuman uses a Stripe-style environment system:

Environment Purpose Credits
Test Development & integration testing Not consumed
Live Production usage Consumed

Create environment-specific API keys from your dashboard. For complete details, see Test vs Live Environments.

📖 Overview

VerifyHuman offers four verification products, all accessible through unified API keys with product scopes:

Product Purpose Required Scope Available in Plans
VerifyHuman Liveness detection & bot prevention verifyhuman All plans
VerifyAge Age gating & compliance verifyage All plans
VerifyIdentity KYC with ID verification verifyidentity All plans
VerifyCompliance KYC+ with AML/sanctions screening verifycompliance Pro & Enterprise only

Plan Access

🔐 Authentication

All API requests require authentication using unified API keys. Generate your keys from the VerifyHuman Dashboard.

Unified API Key Format

All API keys use the same format with product scopes:

Type Format Example
API Key vhk-{32chars} vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
API Secret vhsk-{48chars} vhsk-a1b2c3d4e5f6g7h8i9j0...

When creating an API key, select which product scopes it can access (e.g., verifyhuman, verifyage, verifyidentity, verifycompliance).

Authentication Methods

Header Authentication (Recommended)

X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Form Data Authentication (VerifyHuman only)

Content-Type: multipart/form-data

clientKey=vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Base URL

Production: https://app.verifyhuman.io

🔍 Product Endpoints

VerifyHuman - Liveness & Bot Detection

Bot prevention and human verification using AI-powered liveness detection.

POST /api/verify

Upload an image or video for liveness verification.

Authentication: X-API-Key header or clientKey form field (requires verifyhuman scope)

Request

POST /api/verify
Content-Type: multipart/form-data
X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

file=<image-or-video-file>

Parameters:

Success Response (200)

{
  "verification_id": "ver_abc123",
  "status": "PASS",
  "confidence": 95.7,
  "is_real_face": true,
  "face_detected": true,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "timestamp": "2025-01-15T10:30:00Z"
}

Failure Response (200)

{
  "verification_id": "ver_def456",
  "status": "FAIL",
  "confidence": 65.2,
  "face_detected": false,
  "error": "Low confidence score or no face detected"
}

Example Request

curl -X POST https://app.verifyhuman.io/api/verify \
  -H "X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -F "file=@selfie.jpg"

GET /api/status/{verification_id}

Get verification status by ID.

Request

GET /api/status/ver_abc123

Response (200)

{
  "verification_id": "ver_abc123",
  "status": "PASS",
  "confidence": 95.7,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:30:03Z"
}

POST /api/validate

Server-side token validation.

Request

POST /api/validate
Authorization: Bearer sk_live_your_secret
Content-Type: application/json

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Response (200)

{
  "valid": true,
  "verification_id": "ver_abc123",
  "status": "PASS",
  "confidence": 95.7
}

VerifyAge - Age Verification

AI-powered age verification using selfie age estimation and optional ID verification.

POST /api/v1/verify-age/init

Initialize age verification session and get compliance rules.

Authentication: X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6...

Request

POST /api/v1/verify-age/init
X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Content-Type: application/json

{
  "use_case": "alcohol",
  "state_code": "CA",
  "min_age": 21
}

Response (200)

{
  "success": true,
  "use_case": "alcohol",
  "min_age": 21,
  "description": "Alcohol purchase and consumption",
  "strict_mode": false,
  "notes": "Federal law requires 21+ nationwide"
}

POST /api/v1/verify-age/step1

Submit date of birth for initial age check.

Request

{
  "date_of_birth": "1990-05-15",
  "use_case": "alcohol",
  "min_age": 21
}

Success Response (200)

{
  "success": true,
  "proceed_to_step2": true,
  "user_age": 35,
  "min_age_required": 21,
  "message": "DOB verified. Proceed to selfie verification.",
  "credits_consumed": 0
}

Underage Response (200)

{
  "verified": false,
  "underage": true,
  "user_age": 17,
  "min_age_required": 21,
  "status": "failed",
  "message": "Access denied. Minimum age is 21.",
  "credits_consumed": 0
}

POST /api/v1/verify-age/step2

Submit selfie for AI age estimation and liveness check.

Request

{
  "image_selfie_b64": "base64_encoded_image",
  "user_age": 35,
  "min_age": 21
}

Verified Response (200)

{
  "verified": true,
  "method": "selfie",
  "estimated_age": 28,
  "age_range": {
    "Low": 25,
    "High": 31
  },
  "confidence": 92.5,
  "is_real_person": true,
  "requires_id": false,
  "status": "success",
  "credits_consumed": 10,
  "credits_remaining": 490
}

ID Required Response (200)

{
  "verified": false,
  "requires_id": true,
  "proceed_to_step3": true,
  "estimated_age": 19,
  "age_range": {
    "Low": 17,
    "High": 22
  },
  "message": "ID verification required to confirm age.",
  "reason": "estimated_age_below_threshold",
  "credits_consumed": 10
}

POST /api/v1/verify-age/step3

Verify age using government ID (conditional - only if step 2 fails).

Request

{
  "image_selfie_b64": "base64_encoded_selfie",
  "image_id_b64": "base64_encoded_id",
  "min_age": 21
}

Success Response (200)

{
  "verified": true,
  "method": "selfie+id",
  "actual_age": 24,
  "dob": "03/15/1999",
  "face_match_confidence": 95.2,
  "status": "success",
  "credits_remaining": 480
}

POST /api/v1/verify-age/verify

Complete verification in a single call (alternative to multi-step flow).

Request

{
  "image_selfie_b64": "base64_encoded_selfie",
  "image_id_b64": "base64_encoded_id (optional)",
  "use_case": "adult",
  "min_age": 18
}

Response: Same as step2/step3 responses

VerifyIdentity - KYC Verification

Know Your Customer (KYC) verification with selfie + ID document matching.

POST /api/identity/v1/submit

Submit selfie and ID documents for identity verification.

Authentication: X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6... or X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6...

Request

POST /api/identity/v1/submit
X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Content-Type: application/json

{
  "selfie_b64": "base64_encoded_selfie",
  "id_front_b64": "base64_encoded_id_front",
  "id_back_b64": "base64_encoded_id_back (optional)",
  "name": "John Doe (optional)",
  "date_of_birth": "1990-05-15 (optional)",
  "address": "123 Main St (optional)"
}

Success Response (200)

{
  "success": true,
  "verified": true,
  "verification_id": "ver_kyc_abc123",
  "confidence": 94.5,
  "face_match": {
    "similarity": 95.8,
    "is_match": true
  },
  "document_data": {
    "name": "JOHN DOE",
    "date_of_birth": "05/15/1990",
    "document_type": "Driver License",
    "document_number": "D1234567",
    "expiry_date": "05/15/2028",
    "issuing_country": "USA"
  },
  "authenticity": {
    "is_genuine": true,
    "confidence": 92.3
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "credits_consumed": 30,
  "credits_remaining": 970
}

Failure Response (200)

{
  "success": false,
  "verified": false,
  "verification_id": "ver_kyc_def456",
  "error": "Face mismatch: Selfie does not match ID photo",
  "face_match": {
    "similarity": 45.2,
    "is_match": false
  },
  "credits_consumed": 30
}

Privacy Note: All images are processed in-memory and immediately discarded. No biometric data is stored.

VerifyCompliance - KYC+ with AML/Sanctions

Advanced KYC with integrated AML/PEP/Sanctions screening. Available on Pro & Enterprise plans only.

POST /api/kyc/v1/submit_plus

Submit identity verification with compliance screening.

Authentication: X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6...

Request

POST /api/kyc/v1/submit_plus
X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Content-Type: application/json

{
  "selfie_b64": "base64_encoded_selfie",
  "id_front_b64": "base64_encoded_id_front",
  "id_back_b64": "base64_encoded_id_back (optional)",
  "gender": "male (optional)"
}

Success Response - No Compliance Hits (200)

{
  "success": true,
  "verified": true,
  "verification_id": "ver_kycp_abc123",
  "confidence": 94.5,
  "face_match": {
    "similarity": 95.8,
    "is_match": true
  },
  "document_data": {
    "name": "JOHN DOE",
    "date_of_birth": "05/15/1990",
    "document_type": "Driver License"
  },
  "compliance_screening": {
    "performed": true,
    "status": "Cleared",
    "total_hits": 0,
    "message": "No matches found in AML/PEP/Sanctions databases",
    "timestamp": "2025-01-15T10:30:05Z"
  },
  "credits_consumed": 50,
  "credits_remaining": 950
}

Response - Compliance Hits Detected (200)

{
  "success": true,
  "verified": false,
  "verification_id": "ver_kycp_def456",
  "compliance_screening": {
    "performed": true,
    "status": "Potential Match",
    "total_hits": 2,
    "message": "Potential matches detected - review required",
    "found_records": [
      {
        "name": "John M. Doe",
        "category": "PEP",
        "match_score": 87.5
      },
      {
        "name": "J. Doe",
        "category": "Sanctions",
        "match_score": 72.3
      }
    ],
    "timestamp": "2025-01-15T10:30:05Z"
  },
  "credits_consumed": 50
}

POST /api/kyc/v1/generate_report

Generate encrypted PDF compliance report (available after verification with hits).

Request

POST /api/kyc/v1/generate_report
X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Content-Type: application/json

{
  "verification_id": "ver_kycp_def456",
  "report_password": "SecurePassword123 (optional)"
}

Success Response (200)

{
  "success": true,
  "pdf_base64": "JVBERi0xLjQKJeLjz9MK...",
  "size_bytes": 245678,
  "encrypted": true,
  "filename": "compliance_report_ver_kycp_def456.pdf"
}

Report Features:

Privacy Guarantee: Reports contain only screening results, never raw biometric data.

🚨 Error Handling

HTTP Status Codes

Code Meaning Description
200 OK Request successful (check response body for verification status)
400 Bad Request Missing or invalid parameters
401 Unauthorized Invalid or missing API key
402 Payment Required Insufficient credits
403 Forbidden Product not available in your plan
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error

Error Response Format

{
  "error": "Human-readable error message",
  "status": "ERROR",
  "code": "ERROR_CODE (optional)"
}

Common Error Responses

Insufficient Credits

{
  "error": "Insufficient credits",
  "status": "ERROR",
  "credits_remaining": 5,
  "credits_required": 10
}

Invalid API Key

{
  "error": "Invalid API key or wrong product scope",
  "status": "ERROR",
  "hint": "This endpoint requires a unified API key with verifyage scope (vhk-...)"
}

Plan Restriction

{
  "error": "VerifyCompliance requires Pro or Enterprise plan",
  "status": "ERROR",
  "upgrade_url": "https://app.verifyhuman.io/dashboard/billing"
}

📊 Rate Limits

VerifyHuman uses an enterprise-grade rate limiting system with three dimensions:

Plan-Based Throughput Limits

Limits apply per API key based on your subscription plan:

Plan Verification RPS Verification Burst Read RPS Read Burst
Free 1 5 10 10
Starter 2 10 20 20
Growth 5 50 50 100
Pro 10 100 100 200
Enterprise 25 500 250 1,000

Product Sensitivity Multipliers

Verification endpoints have product-specific multipliers that adjust effective limits:

Product Multiplier Effect on Limits
VerifyHuman 1.0x Base limit
VerifyAge 1.5x 67% of base
VerifyIdentity 2.0x 50% of base
VerifyCompliance 3.0x 33% of base

For example, a Growth plan user has 5 RPS for VerifyHuman, but only ~1.67 RPS for VerifyCompliance.

Endpoint Categories

Category Description Examples
Verification Billable verification requests /api/verify, /api/v1/verify-age/*
Read Status checks, result fetching /api/verification/{id}, /api/usage
Health Monitoring endpoints /api/health

Rate Limit Headers

All responses include standards-compliant rate limit headers:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1673778000
Retry-After: 1
Header Description
X-RateLimit-Limit Maximum requests allowed in the current window
X-RateLimit-Remaining Requests remaining in the current window
X-RateLimit-Reset Unix timestamp when the limit resets
Retry-After Seconds to wait before retrying (on 429 responses)

Rate Limit Exceeded Response (429)

When rate limited, you'll receive a 429 response:

{
  "success": false,
  "error": "Rate limit exceeded",
  "error_code": "RATE_LIMITED",
  "message": "Rate limit exceeded. Please wait 1 seconds before retrying.",
  "details": {
    "limit": 50,
    "remaining": 0,
    "retry_after": 1
  }
}

Credits Exhausted Response (402)

For billable verification endpoints, if you have no credits available:

{
  "success": false,
  "error": "Credits exhausted",
  "error_code": "CREDITS_EXHAUSTED",
  "message": "No credits available. Please purchase credits or upgrade your plan.",
  "upgrade_url": "/dashboard/billing"
}

Note: Test environment API keys never trigger 402 errors.

Best Practices

  1. Implement exponential backoff - When receiving 429, wait for Retry-After seconds, then retry with exponential delays
  2. Add jitter - Randomize retry delays to avoid thundering herd problems
  3. Use idempotency keys - For verification requests, include unique identifiers to prevent duplicate charges
  4. Monitor headers - Track X-RateLimit-Remaining to proactively slow down before hitting limits
  5. Upgrade when needed - If consistently hitting limits, consider upgrading your plan

🔗 CORS Support

All API endpoints include CORS headers for cross-origin requests:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-API-Key, Authorization

🧪 Testing

Demo Mode

Use demo API keys for testing without consuming credits:

vhk-demo_test123456789abcdefghijklm    # Demo key for all products

All products (VerifyHuman, VerifyAge, VerifyIdentity, VerifyCompliance) use the unified key format with product-specific scopes.

Demo mode behavior:

🔒 Privacy & Security

Zero-Storage Policy

We never store verification media. All images and videos are:

Data Retention

We only store:

Compliance

📞 Support

Reporting & Analytics

VerifyHuman provides comprehensive analytics and reporting APIs for monitoring verification patterns and performance.

Reporting API (V1)

Endpoint Description Plan
GET /api/reports/overview Dashboard summary metrics All
GET /api/reports/volume Volume over time All
GET /api/reports/usage Usage by product/key All
GET /api/reports/risk-summary Risk and confidence metrics Growth+
GET /api/reports/widget-performance Per-widget analytics Growth+

Reporting API (V2.1)

Endpoint Description Plan
GET /api/reports/v21/verification Verification with compliance scoring All
GET /api/reports/v21/full Full report with credits intelligence Role-gated

Export API

Endpoint Description Plan
POST /api/reports/exports Create export job Growth+
GET /api/reports/exports List export jobs Growth+
GET /api/reports/exports/{id}/download Download export Growth+

For complete documentation, see:

Additional Resources