VerifyHuman API Documentation

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

Last Updated: November 30, 2025
API Version: 2.1.0

📋 Table of Contents

Overview
Authentication
Product Endpoints
Error Handling
Rate Limits

📖 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

Free, Starter, Growth: VerifyHuman, VerifyAge, VerifyIdentity
Pro & Enterprise: All products including VerifyCompliance

🔐 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:

file (required): Image file (JPG, PNG) or video (MP4, WebM), max 5MB
clientKey (optional): API key via form data

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:

AES-256 encryption (if password provided)
Detailed AML/PEP/Sanctions findings
Match scores and risk assessments
Secure, one-time download

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

Rate limits apply per API key:

Plan	Requests/Minute	Daily Limit
Free	10	50 verifications
Starter	60	1,000 verifications
Growth	300	10,000 verifications
Pro	600	100,000 verifications
Enterprise	1,000	Unlimited

Rate Limit Headers

Response headers include rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1673778000

Rate Limit Exceeded Response (429)

{
  "error": "Rate limit exceeded",
  "status": "ERROR",
  "retry_after": 60,
  "limit": "60 requests/minute"
}

🔗 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:

Always returns successful verification
Simulates realistic processing delay (1-3 seconds)
No credit consumption
Generates valid response structures

🔒 Privacy & Security

Zero-Storage Policy

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

Processed in-memory only
Immediately discarded after verification
Never saved to disk, cache, or logs
Not accessible after verification completes

Data Retention

We only store:

Verification ID and timestamp
Status (PASS/FAIL) and confidence score
No facial data, images, or biometric information
For VerifyCompliance: Screening hit/no-hit status only (not raw data)

Compliance

GDPR Compliant: No biometric data storage
CCPA Compliant: Minimal data retention
SOC 2 Type II: Annual security audits
Encrypted Transit: All data transmitted via TLS 1.3

📞 Support

API Issues: support@verifyhuman.io
Documentation: Submit improvements via GitHub
Status Page: status.verifyhuman.io
Developer Portal: app.verifyhuman.io/dashboard

VerifyHuman API Documentation

📋 Table of Contents

📖 Overview

Plan Access

🔐 Authentication

Unified API Key Format

Authentication Methods

Base URL

🔍 Product Endpoints

VerifyHuman - Liveness & Bot Detection

POST /api/verify

GET /api/status/{verification_id}

POST /api/validate

VerifyAge - Age Verification

POST /api/v1/verify-age/init

POST /api/v1/verify-age/step1

POST /api/v1/verify-age/step2

POST /api/v1/verify-age/step3

POST /api/v1/verify-age/verify

VerifyIdentity - KYC Verification

POST /api/identity/v1/submit

VerifyCompliance - KYC+ with AML/Sanctions

POST /api/kyc/v1/submit_plus

POST /api/kyc/v1/generate_report

🚨 Error Handling

HTTP Status Codes

Error Response Format

Common Error Responses

📊 Rate Limits

Rate Limit Headers

Rate Limit Exceeded Response (429)

🔗 CORS Support

🧪 Testing

Demo Mode

🔒 Privacy & Security

Zero-Storage Policy

Data Retention

Compliance

📞 Support

📚 Additional Resources