Dashboard

VerifyAge API Documentation

VerifyAge is an AI-powered age verification service using date of birth entry and conditional ID verification for compliance with age-restricted content and services.

Features

Quick Start

1. Get Your VerifyAge API Key

  1. Log in to your dashboard
  2. Go to API Keys section
  3. Select "VerifyAge (Age Verification)" scope for your API key
  4. Create your API key (format: vhk-{32chars})
  5. Save your secret key securely (format: vhsk-{48chars})

The fastest way to get started is using our Integration Wizard:

  1. Go to VerifyAge Wizard in your dashboard
  2. Configure your settings:
    • Select your use case (adult, alcohol, tobacco, etc.)
    • Set minimum age requirement
    • Choose US state for compliance (optional)
    • Customize button text and messages
  3. Choose integration type (Widget or API)
  4. Copy the generated code
  5. Paste into your website

The wizard generates production-ready code customized for your specific needs.

3. JavaScript Widget Integration (Manual Setup)

The easiest way to integrate VerifyAge is using our JavaScript widget:

<!-- Include Bootstrap 5 (required) -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js"></script>

<!-- Include Font Awesome (required) -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css">

<!-- Include VerifyAge Widget -->
<script src="https://verifyhuman.io/static/verifyage.js"></script>

<script>
// Initialize VerifyAge
const verifyAge = new VerifyAge();

verifyAge.init({
    apiKey: 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
    minAge: 21,  // Minimum age requirement
    useCase: 'alcohol',  // Use case: adult, alcohol, tobacco, cannabis, gambling, custom
    onSuccess: function(result) {
        console.log('Age verified!', result);
        // Grant access to restricted content
    },
    onFailure: function(error) {
        console.error('Verification failed:', error);
        // Handle failure
    }
});

// Trigger verification (e.g., on button click)
document.getElementById('verify-btn').addEventListener('click', function() {
    verifyAge.open();
});
</script>

API Endpoints

Initialize Verification

Get compliance rules for your use case.

Endpoint: POST /api/v1/verify-age/init

Request:

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

Response:

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

Step 1: DOB Verification

Submit user's date of birth for initial age verification.

Endpoint: POST /api/v1/verify-age/step1

Headers:

Request:

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

Success Response (Proceed to Step 2):

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

Failure Response (Underage):

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

Step 2: Selfie Verification

Submit selfie for liveness detection and age estimation.

Endpoint: POST /api/v1/verify-age/step2

Headers:

Request:

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

Success Response (Verified via Selfie):

{
    "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": 5,
    "credits_remaining": 495
}

Partial Response (ID Required):

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

Step 3: ID Verification (Conditional)

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

Endpoint: POST /api/v1/verify-age/step3

Headers:

Request:

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

Success Response:

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

Failure Response:

{
    "verified": false,
    "status": "failed",
    "reason": "below_minimum_age",
    "actual_age": 17,
    "minimum_age": 21,
    "credits_remaining": 495
}

Complete Verification (Single Call)

Perform complete verification in one request.

Endpoint: POST /api/v1/verify-age/verify

Request:

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

Use Cases

VerifyAge supports common age-restricted use cases with automatic compliance rules:

Use Case Min Age Description
adult 18 Adult content and services
alcohol 21 Alcohol purchase (US federal law)
tobacco 21 Tobacco and vaping products
cannabis 21 Cannabis products (where legal)
gambling 21 Gambling and gaming services
custom Variable User-defined minimum age

State-Specific Compliance

VerifyAge includes built-in compliance data for US state laws. Some states require age verification for specific content:

States with adult content verification laws:

Compliance FAQ

General Questions

Q: Is VerifyAge legally compliant for age-restricted content? A: VerifyAge uses AI-powered facial age estimation and government ID verification to verify age. It meets or exceeds requirements in most jurisdictions, but you should consult with legal counsel to ensure compliance with your specific use case and location.

Q: Which states require age verification for adult content? A: As of 2024, the following states have passed age verification laws for adult content: Utah, Louisiana, Arkansas, Texas, Montana, Virginia, Mississippi, North Carolina, Kansas, Idaho, Indiana, Kentucky, and Nebraska. More states are considering similar legislation.

Q: What is the minimum age for different use cases? A:

Q: Can I use VerifyAge internationally? A: Currently, VerifyAge is optimized for US compliance. International support is coming soon. The facial age estimation works globally, but compliance rules are currently US-focused.

Technical Questions

Q: How accurate is facial age estimation? A: Our AI model provides age ranges with high confidence. For borderline cases, we recommend the two-step verification (facial + ID) for maximum accuracy and legal protection.

Q: What happens to uploaded images? A: Nothing. All images are processed in-memory and immediately discarded. We never store, log, or retain any verification media. This is our privacy guarantee.

Q: How long does verification take? A: Facial age estimation typically completes in 1-2 seconds. ID verification (if required) adds another 2-3 seconds. Total time is usually under 5 seconds.

Q: Can users bypass the verification? A: VerifyAge uses advanced AI to detect spoofing attempts. We recommend implementing server-side validation and session management to prevent bypass attempts.

Business Questions

Q: How much does VerifyAge cost? A: Each verification costs 10 credits, regardless of outcome. New VerifyAge API keys include a free trial: 30 days or 50 verifications (whichever comes first). After trial, you'll need a Growth plan or higher.

Q: What counts as a verification? A: Each API call to /verify-age/step1 or /verify-age/verify counts as one verification (10 credits). The /init endpoint is free. If Step 1 requires ID verification, Step 2 does not consume additional credits.

Q: Can I get a refund if verification fails? A: No. Credits are consumed whether verification passes or fails, as our AI processing occurs regardless of the outcome.

Q: What if I run out of credits? A: The API will return an error indicating insufficient credits. Users must purchase additional credits or upgrade their plan to continue verifying.

Privacy & Security

Q: Is VerifyAge GDPR/CCPA compliant? A: Yes. We process images in-memory only and never store biometric data. No personal information is retained after verification completes.

Q: Do you share data with third parties? A: No. Images are processed by our AI systems and are never stored or shared. All data is processed in-memory only and immediately discarded.

Q: How should I store verification results? A: Store only the minimum necessary data (e.g., user ID, verification status, timestamp). Never store images or biometric data. Implement auto-expiry for verification results (e.g., 24-48 hours).

Q: What if my site gets hacked? A: Since VerifyAge doesn't store images or biometric data, there's nothing sensitive to steal. At most, attackers could see verification timestamps and pass/fail status.

Implementation Questions

Q: Do I need to collect user IDs? A: Not required for facial age estimation. ID verification (Step 2) is only triggered for borderline cases or high-risk scenarios. Users can choose to skip ID verification in some implementations.

Q: Can I customize the widget? A: Yes. Use the VerifyAge Wizard to customize button text, messages, and behavior. For advanced customization, use the API directly.

Q: What image formats are supported? A: JPEG, PNG, and WebP. Images should be base64-encoded for API calls. The widget handles encoding automatically.

Q: What's the maximum image size? A: 10MB per image. Larger images will be rejected. For best results, use images between 500KB-2MB.

Pricing & Credits

Privacy & Security

Zero-Storage Policy

⚠️ PRIVACY GUARANTEE: VerifyAge never stores verification media.

Security Best Practices

  1. Never expose your API key in frontend code
  2. Use server-side verification for production apps
  3. Implement rate limiting to prevent abuse
  4. Validate results server-side before granting access

Error Handling

Common Error Responses

Insufficient Credits:

{
    "error": "Insufficient credits",
    "status": "ERROR",
    "message": "VerifyAge requires 10 credits per verification",
    "credits_remaining": 5
}

Trial Expired:

{
    "error": "VerifyAge trial expired",
    "status": "ERROR",
    "message": "Upgrade to Growth plan or higher to continue using VerifyAge",
    "upgrade_url": "/dashboard/billing"
}

Invalid API Key:

{
    "error": "This endpoint requires a VerifyAge API key",
    "status": "ERROR",
    "hint": "Generate a VerifyAge API key from your dashboard"
}

Code Examples

Python Example

import requests
import base64

# Read and encode image
with open('selfie.jpg', 'rb') as f:
    selfie_b64 = base64.b64encode(f.read()).decode()

# Call VerifyAge API
response = requests.post(
    'https://verifyhuman.io/api/v1/verify-age/step1',
    headers={
        'X-API-Key': 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        'Content-Type': 'application/json'
    },
    json={
        'image_selfie_b64': selfie_b64,
        'min_age': 21,
        'use_case': 'alcohol'
    }
)

result = response.json()
if result.get('verified'):
    print('Age verified!')
else:
    print('Verification failed or ID required')

Node.js Example

const axios = require('axios');
const fs = require('fs');

// Read and encode image
const selfieBuffer = fs.readFileSync('selfie.jpg');
const selfieB64 = selfieBuffer.toString('base64');

// Call VerifyAge API
axios.post('https://verifyhuman.io/api/v1/verify-age/step1', {
    image_selfie_b64: selfieB64,
    min_age: 21,
    use_case: 'alcohol'
}, {
    headers: {
        'X-API-Key': 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    if (response.data.verified) {
        console.log('Age verified!');
    } else {
        console.log('Verification failed or ID required');
    }
})
.catch(error => {
    console.error('Error:', error.response.data);
});

PHP Example

<?php
// Read and encode image
$selfie = base64_encode(file_get_contents('selfie.jpg'));

// Call VerifyAge API
$ch = curl_init('https://verifyhuman.io/api/v1/verify-age/step1');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'image_selfie_b64' => $selfie,
    'min_age' => 21,
    'use_case' => 'alcohol'
]));

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['verified'] ?? false) {
    echo 'Age verified!';
} else {
    echo 'Verification failed or ID required';
}
?>

Testing

Use demo mode for development testing:

  1. Use a demo API key for testing
  2. Demo responses will return simulated age estimates
  3. Perfect for testing integration without consuming credits

Support

Changelog

Version 1.0 (Current)