VerifyHuman API Documentation

VerifyHuman is an AI-powered liveness detection service that confirms real human users vs bots, preventing automated abuse across your applications.

Features

AI-Powered Liveness Detection: Advanced face detection and liveness verification
Anti-Bot Protection: Prevents automated sign-ups, spam, and abuse
Fast Integration: Widget embed or REST API in minutes
Real-Time Verification: Instant results with confidence scores
Privacy-First: All data processed in-memory, never stored
Free Trial: 50 free verifications to get started
Cross-Origin Support: Works on any domain with CORS enabled

Quick Start

1. Get Your VerifyHuman API Key

Log in to your dashboard
Go to API Keys section
Select "VerifyHuman (Face Verification)" scope for your API key
Create your API key (format: vhk-{32chars})
Save your secret key securely (format: vhsk-{48chars})

2. Use the Integration Wizard (Recommended)

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

Go to VerifyHuman Wizard in your dashboard
Select your use case:
- Anti-bot account registration
- Anti-bot comment/post protection
- Sensitive login verification
- Form submission protection
- Checkout bot prevention
- Custom integration
Choose integration type (Widget or REST API)
Copy the generated code
Paste into your application

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

The easiest way to integrate VerifyHuman is using our JavaScript widget.

Basic Setup

<!-- Include VerifyHuman Widget -->
<script src="https://app.verifyhuman.io/widget.js"></script>

<script>
// Initialize VerifyHuman
VerifyHuman.init({
    clientKey: 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
    onSuccess: function(token) {
        console.log('Verification successful!', token);
        // Send token to your backend for validation
        verifyOnBackend(token);
    },
    onFailure: function(error) {
        console.error('Verification failed:', error);
        alert('Human verification failed. Please try again.');
    },
    onProgress: function(message) {
        console.log('Progress:', message);
    }
});

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

// Validate token on your backend
function verifyOnBackend(token) {
    fetch('/api/verify-human', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ verificationToken: token })
    })
    .then(response => response.json())
    .then(data => {
        if (data.verified) {
            console.log('Backend validation successful');
            // Proceed with user action (signup, comment, etc.)
        }
    });
}
</script>

<button id="verify-btn">Verify I'm Human</button>

REST API Integration

For backend implementations or custom UIs, use our REST API directly.

Endpoint

POST https://app.verifyhuman.io/api/verify

Headers

X-API-Key: Your unified API key with verifyhuman scope (vhk-...)
Content-Type: multipart/form-data

Request Parameters

Parameter	Type	Required	Description
`file`	File	Yes	Selfie image or video (JPEG, PNG, MP4, WebM)
`clientKey`	String	Yes	Your API client key

Response

{
    "status": "PASS",
    "confidence": 98.5,
    "is_real_face": true,
    "face_detected": true,
    "verification_id": "vh_1234567890abcdef",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "timestamp": "2025-01-15T10:30:00Z"
}

Status Values:

PASS - Human verified successfully
FAIL - No face detected or liveness check failed
ERROR - Processing error (check error field)

Code Examples

Python (Flask)

from flask import Flask, request, jsonify, render_template
import requests
import base64

app = Flask(__name__)
VERIFYHUMAN_API_KEY = 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'
VERIFYHUMAN_API_URL = 'https://app.verifyhuman.io/api/verify'

@app.route('/signup', methods=['GET'])
def signup_page():
    return render_template('signup.html')

@app.route('/api/signup', methods=['POST'])
def signup():
    """Handle user registration with VerifyHuman protection"""

    # Get registration data
    email = request.form.get('email')
    password = request.form.get('password')
    selfie_data = request.form.get('selfie')  # Base64 image from frontend

    # Verify human using VerifyHuman API
    try:
        # Convert base64 to file
        import io
        image_data = base64.b64decode(selfie_data.split(',')[1])
        image_file = io.BytesIO(image_data)

        # Call VerifyHuman API
        response = requests.post(
            VERIFYHUMAN_API_URL,
            headers={'X-API-Key': VERIFYHUMAN_API_KEY},
            files={'file': ('selfie.jpg', image_file, 'image/jpeg')},
            data={'clientKey': VERIFYHUMAN_API_KEY}
        )

        result = response.json()

        if result.get('status') != 'PASS':
            return jsonify({
                'success': False,
                'error': 'Human verification failed. Bots not allowed.'
            }), 403

        # Verification passed - proceed with registration
        # ... create user account ...

        return jsonify({
            'success': True,
            'message': 'Account created successfully!',
            'verification_id': result.get('verification_id')
        })

    except Exception as e:
        return jsonify({
            'success': False,
            'error': f'Verification error: {str(e)}'
        }), 500

if __name__ == '__main__':
    app.run(debug=True)

Frontend (signup.html):

<!DOCTYPE html>
<html>
<head>
    <title>Sign Up</title>
    <script src="https://app.verifyhuman.io/widget.js"></script>
</head>
<body>
    <h2>Create Account</h2>
    <form id="signupForm">
        <input type="email" name="email" placeholder="Email" required>
        <input type="password" name="password" placeholder="Password" required>
        <button type="button" id="verifyBtn">Verify & Sign Up</button>
    </form>

    <script>
    VerifyHuman.init({
        clientKey: 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        onSuccess: function(token) {
            // Get form data
            const formData = new FormData(document.getElementById('signupForm'));

            // Add verification token
            formData.append('verificationToken', token);

            // Submit to backend
            fetch('/api/signup', {
                method: 'POST',
                body: formData
            })
            .then(res => res.json())
            .then(data => {
                if (data.success) {
                    alert('Account created successfully!');
                    window.location.href = '/dashboard';
                } else {
                    alert('Signup failed: ' + data.error);
                }
            });
        },
        onFailure: function(error) {
            alert('Human verification failed. Please try again.');
        }
    });

    document.getElementById('verifyBtn').addEventListener('click', function() {
        VerifyHuman.open();
    });
    </script>
</body>
</html>

Anti-Bot Comment Protection

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)
VERIFYHUMAN_API_KEY = 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'

@app.route('/api/comments', methods=['POST'])
def post_comment():
    """Post comment with anti-bot verification"""

    post_id = request.json.get('post_id')
    comment_text = request.json.get('comment')
    verification_token = request.json.get('verification_token')

    # Validate VerifyHuman token on backend
    # (In production, verify JWT signature or make API call to validate)
    if not verification_token:
        return jsonify({
            'success': False,
            'error': 'Human verification required'
        }), 403

    # Token validated - save comment
    # ... save to database ...

    return jsonify({
        'success': True,
        'message': 'Comment posted successfully',
        'comment_id': '12345'
    })

if __name__ == '__main__':
    app.run(debug=True)

JavaScript (Node.js + Express)

Backend API

const express = require('express');
const multer = require('multer');
const FormData = require('form-data');
const axios = require('axios');

const app = express();
const upload = multer({ storage: multer.memoryStorage() });

const VERIFYHUMAN_API_KEY = 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
const VERIFYHUMAN_API_URL = 'https://app.verifyhuman.io/api/verify';

// Anti-bot signup endpoint
app.post('/api/signup', upload.single('selfie'), async (req, res) => {
    try {
        const { email, password } = req.body;
        const selfie = req.file;

        if (!selfie) {
            return res.status(400).json({
                success: false,
                error: 'Selfie required for verification'
            });
        }

        // Verify human with VerifyHuman API
        const formData = new FormData();
        formData.append('file', selfie.buffer, {
            filename: 'selfie.jpg',
            contentType: selfie.mimetype
        });
        formData.append('clientKey', VERIFYHUMAN_API_KEY);

        const response = await axios.post(VERIFYHUMAN_API_URL, formData, {
            headers: {
                'X-API-Key': VERIFYHUMAN_API_KEY,
                ...formData.getHeaders()
            }
        });

        const result = response.data;

        if (result.status !== 'PASS') {
            return res.status(403).json({
                success: false,
                error: 'Human verification failed. Bots not allowed.'
            });
        }

        // Verification passed - create account
        // ... create user in database ...

        res.json({
            success: true,
            message: 'Account created successfully!',
            verification_id: result.verification_id
        });

    } catch (error) {
        console.error('Signup error:', error);
        res.status(500).json({
            success: false,
            error: 'Signup failed: ' + error.message
        });
    }
});

app.listen(3000, () => {
    console.log('Server running on port 3000');
});

React Component

import React, { useState } from 'react';

function SignupForm() {
    const [formData, setFormData] = useState({
        email: '',
        password: ''
    });
    const [loading, setLoading] = useState(false);
    const [message, setMessage] = useState('');

    const handleVerifyClick = () => {
        // Initialize VerifyHuman widget
        window.VerifyHuman.init({
            clientKey: 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
            onSuccess: async (token) => {
                setLoading(true);

                try {
                    // Submit form with verification token
                    const response = await fetch('/api/signup', {
                        method: 'POST',
                        headers: {
                            'Content-Type': 'application/json'
                        },
                        body: JSON.stringify({
                            ...formData,
                            verificationToken: token
                        })
                    });

                    const data = await response.json();

                    if (data.success) {
                        setMessage('Account created successfully!');
                        window.location.href = '/dashboard';
                    } else {
                        setMessage('Error: ' + data.error);
                    }
                } catch (error) {
                    setMessage('Signup failed: ' + error.message);
                } finally {
                    setLoading(false);
                }
            },
            onFailure: (error) => {
                setMessage('Human verification failed. Please try again.');
            }
        });

        // Open verification modal
        window.VerifyHuman.open();
    };

    return (
        <div className="signup-form">
            <h2>Create Account</h2>

            <input
                type="email"
                placeholder="Email"
                value={formData.email}
                onChange={(e) => setFormData({...formData, email: e.target.value})}
            />

            <input
                type="password"
                placeholder="Password"
                value={formData.password}
                onChange={(e) => setFormData({...formData, password: e.target.value})}
            />

            <button onClick={handleVerifyClick} disabled={loading}>
                {loading ? 'Creating Account...' : 'Verify & Sign Up'}
            </button>

            {message && <div className="message">{message}</div>}
        </div>
    );
}

export default SignupForm;

PHP

<?php
// Anti-bot signup with VerifyHuman

$VERIFYHUMAN_API_KEY = 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
$VERIFYHUMAN_API_URL = 'https://app.verifyhuman.io/api/verify';

function verifyHuman($imageData) {
    global $VERIFYHUMAN_API_KEY, $VERIFYHUMAN_API_URL;

    // Convert base64 to file
    $imageData = str_replace('data:image/jpeg;base64,', '', $imageData);
    $imageData = str_replace(' ', '+', $imageData);
    $decodedImage = base64_decode($imageData);

    // Create temporary file
    $tempFile = tmpfile();
    $tempPath = stream_get_meta_data($tempFile)['uri'];
    fwrite($tempFile, $decodedImage);

    // Prepare multipart form data
    $ch = curl_init();

    $postData = array(
        'file' => new CURLFile($tempPath, 'image/jpeg', 'selfie.jpg'),
        'clientKey' => $VERIFYHUMAN_API_KEY
    );

    curl_setopt_array($ch, array(
        CURLOPT_URL => $VERIFYHUMAN_API_URL,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $postData,
        CURLOPT_HTTPHEADER => array(
            'X-API-Key: ' . $VERIFYHUMAN_API_KEY
        )
    ));

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    fclose($tempFile);

    if ($httpCode !== 200) {
        return array('status' => 'ERROR', 'error' => 'API request failed');
    }

    return json_decode($response, true);
}

// Handle signup request
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $email = $_POST['email'] ?? '';
    $password = $_POST['password'] ?? '';
    $selfieData = $_POST['selfie'] ?? '';

    // Verify human
    $verification = verifyHuman($selfieData);

    if ($verification['status'] !== 'PASS') {
        http_response_code(403);
        echo json_encode(array(
            'success' => false,
            'error' => 'Human verification failed. Bots not allowed.'
        ));
        exit;
    }

    // Verification passed - create account
    // ... save user to database ...

    echo json_encode(array(
        'success' => true,
        'message' => 'Account created successfully!',
        'verification_id' => $verification['verification_id']
    ));
}
?>

cURL

# Direct API call with cURL

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

# Response:
# {
#   "status": "PASS",
#   "confidence": 98.5,
#   "is_real_face": true,
#   "face_detected": true,
#   "verification_id": "vh_1234567890abcdef",
#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "timestamp": "2025-01-15T10:30:00Z"
# }

Common Use Cases

1. Anti-Bot Account Registration

Prevent automated bot signups by requiring liveness verification during registration.

Implementation:

Add "Verify I'm Human" button to signup form
User completes liveness check before form submission
Backend validates verification token
Only verified humans can create accounts

Benefits:

Eliminates bot-created fake accounts
Reduces spam and abuse
Improves user quality

2. Anti-Bot Comment/Post Protection

Stop comment spam by verifying users before allowing posts.

Implementation:

First-time commenters must verify as human
Verification status stored in session/cookie
Verified users can comment freely
Re-verify on suspicious activity

Benefits:

Eliminates spam comments
Maintains community quality
No CAPTCHA friction for real users

Add liveness check to high-value account logins.

Implementation:

Enable for admin accounts, financial transactions, or password changes
Require liveness verification in addition to password
Prevents credential stuffing attacks

Benefits:

Blocks automated credential attacks
Confirms human operator for sensitive actions
Additional security layer beyond passwords

4. Checkout Bot Prevention

Stop scalper bots from purchasing limited inventory.

Implementation:

Require verification at checkout for high-demand items
Verify before "Add to Cart" for limited releases
Rate limit based on verification status

Benefits:

Fair access for real customers
Prevents ticket/product scalping
Reduces inventory hoarding by bots

Best Practices

Security

Always validate on backend: Never trust client-side verification alone
Use HTTPS: Ensure all API calls use secure connections
Rotate API keys: Periodically rotate keys for compromised applications
Domain whitelisting: Restrict API keys to specific domains in production
Monitor abuse: Track verification patterns and flag suspicious activity

User Experience

Clear messaging: Explain why verification is needed
Fallback options: Provide alternative verification for camera issues
Mobile optimization: Test on mobile devices thoroughly
Retry mechanism: Allow users to retry failed verifications
Accessibility: Provide alternatives for users with disabilities

Performance

Async verification: Don't block critical user flows
Cache results: Store verification status in session/cookie
Progressive enhancement: Load widget asynchronously
Error handling: Gracefully handle network failures

Privacy

Data retention: VerifyHuman doesn't store facial data
User consent: Inform users about camera access
Transparency: Explain verification purpose clearly
Compliance: Follow GDPR/CCPA requirements

API Reference

Authentication

All API requests require authentication via the X-API-Key header:

X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Rate Limits

Free tier: 50 requests/day
Starter: 1,000 requests/month
Growth: 10,000 requests/month
Pro: 100,000 requests/month
Enterprise: Unlimited (custom)

Error Codes

Code	Status	Description
200	OK	Verification successful
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid API key
403	Forbidden	Verification failed or quota exceeded
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Response Fields

Field	Type	Description
`status`	String	`PASS`, `FAIL`, or `ERROR`
`confidence`	Float	Confidence score (0-100)
`is_real_face`	Boolean	True if liveness check passed
`face_detected`	Boolean	True if face was found
`verification_id`	String	Unique verification identifier
`token`	String	JWT token for backend validation
`timestamp`	String	ISO 8601 timestamp
`error`	String	Error message (only on errors)

Pricing

VerifyHuman verification uses 1 credit per verification.

Free Trial: 50 verifications
Starter Plan: $19/month (1,000 credits)
Growth Plan: $99/month (10,000 credits)
Pro Plan: $399/month (100,000 credits)
Enterprise: Custom pricing

View detailed pricing

Support

Documentation: https://docs.verifyhuman.io
Integration Wizard: https://app.verifyhuman.io/dashboard/verifyhuman-wizard
API Status: https://status.verifyhuman.io
Email Support: support@verifyhuman.io

Changelog

Version 1.0 (Current)

Initial VerifyHuman release
AI-powered liveness detection
Cross-origin widget support
REST API with multi-language SDKs
Anti-bot protection for signups, comments, logins
Privacy-first in-memory processing

VerifyHuman API Documentation

Features

Quick Start

1. Get Your VerifyHuman API Key

2. Use the Integration Wizard (Recommended)

JavaScript Widget Integration

Basic Setup

REST API Integration

Endpoint

Headers

Request Parameters

Response

Code Examples

Python (Flask)

Anti-Bot User Signup

Anti-Bot Comment Protection

JavaScript (Node.js + Express)

Backend API

React Component

PHP

cURL

Common Use Cases

1. Anti-Bot Account Registration

2. Anti-Bot Comment/Post Protection

3. Sensitive Login Protection

4. Checkout Bot Prevention

Best Practices

Security

User Experience

Performance

Privacy

API Reference

Authentication

Rate Limits

Error Codes

Response Fields

Pricing

Support

Changelog

Version 1.0 (Current)