Dashboard

VerifyIdentity - KYC & Identity Verification

Last Updated: November 30, 2025
Product: VerifyIdentity (KYC)
API Version: 2.1.0

VerifyIdentity is a Know Your Customer (KYC) verification service that combines selfie liveness detection with government ID document verification. It uses AI-powered face matching to confirm the person holding the ID is the same person shown on the document.

✨ Features

🚀 Quick Start

1. Get Your VerifyIdentity API Key

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

2. Integration Methods

Choose the integration method that works best for your application:

Direct API integration with full control over the verification flow.

curl -X POST https://app.verifyhuman.io/api/identity/v1/submit \
  -H "X-API-Key: vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "selfie_b64": "base64_encoded_selfie_image",
    "id_front_b64": "base64_encoded_id_front",
    "id_back_b64": "base64_encoded_id_back"
  }'

Option B: JavaScript Widget

Embed verification directly on your website with our pre-built widget.

<script src="https://app.verifyhuman.io/widget-identity.js"></script>
<script>
VerifyIdentity.init({
  apiKey: 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
  onSuccess: function(result) {
    console.log('KYC verified:', result);
  },
  onFailure: function(error) {
    console.error('Verification failed:', error);
  }
});
</script>

Option C: Hosted Flow (No-Code)

Generate a secure hosted verification page - no coding required. Perfect for quick implementation or non-technical teams.

  1. Go to VerifyIdentity Wizard
  2. Configure settings and branding
  3. Copy the generated link
  4. Share with users or embed on your site

📡 API Reference

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

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

Parameters:

Field Type Required Description
selfie_b64 String Yes Base64-encoded selfie image (JPEG/PNG)
id_front_b64 String Yes Base64-encoded ID front image
id_back_b64 String No Base64-encoded ID back image
name String No User's full name (for validation)
date_of_birth String No DOB in YYYY-MM-DD format (for validation)
address String No User's address (for validation)

Success Response (200)

{
  "success": true,
  "verified": true,
  "verification_id": "ver_kyc_abc123",
  "confidence": 94.5,
  "face_match": {
    "similarity": 95.8,
    "is_match": true,
    "confidence": 96.2
  },
  "document_data": {
    "name": "JOHN DOE",
    "date_of_birth": "05/15/1990",
    "document_type": "Driver License",
    "document_number": "D1234567",
    "expiry_date": "05/15/2028",
    "issuing_state": "CA",
    "issuing_country": "USA",
    "address": "123 MAIN ST, LOS ANGELES, CA 90001"
  },
  "authenticity": {
    "is_genuine": true,
    "confidence": 92.3,
    "checks_passed": ["hologram_present", "barcode_valid", "fonts_match"]
  },
  "data_validation": {
    "name_match": true,
    "dob_match": true,
    "address_match": false,
    "notes": "Address differs slightly from OCR result"
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "credits_consumed": 10,
  "credits_remaining": 990
}

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
  },
  "document_data": {
    "name": "JANE SMITH",
    "extracted": true
  },
  "credits_consumed": 10,
  "credits_remaining": 980
}

🎯 Use Cases

1. Financial Services KYC

Verify customer identity before opening bank accounts or processing loans.

Implementation:

Benefits:

2. Age-Restricted Services

Verify user age and identity for age-restricted products or content.

Implementation:

Benefits:

3. Marketplace Seller Verification

Verify sellers on marketplaces, gig platforms, or rental services.

Implementation:

Benefits:

4. Travel & Hospitality

Verify guest identity for hotel bookings, car rentals, or vacation properties.

Implementation:

Benefits:

💻 Code Examples

Python

import requests
import base64

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

with open('id_front.jpg', 'rb') as f:
    id_front_b64 = base64.b64encode(f.read()).decode()

# Call VerifyIdentity API
response = requests.post(
    'https://app.verifyhuman.io/api/identity/v1/submit',
    headers={
        'X-API-Key': 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        'Content-Type': 'application/json'
    },
    json={
        'selfie_b64': selfie_b64,
        'id_front_b64': id_front_b64,
        'name': 'John Doe',
        'date_of_birth': '1990-05-15'
    }
)

result = response.json()

if result.get('verified'):
    print('✓ Identity verified!')
    print(f"Name: {result['document_data']['name']}")
    print(f"DOB: {result['document_data']['date_of_birth']}")
    print(f"Face match: {result['face_match']['similarity']}%")
else:
    print('✗ Verification failed:', result.get('error'))

Node.js

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

// Read and encode images
const selfieB64 = fs.readFileSync('selfie.jpg').toString('base64');
const idFrontB64 = fs.readFileSync('id_front.jpg').toString('base64');

// Call VerifyIdentity API
axios.post('https://app.verifyhuman.io/api/identity/v1/submit', {
  selfie_b64: selfieB64,
  id_front_b64: idFrontB64,
  name: 'John Doe',
  date_of_birth: '1990-05-15'
}, {
  headers: {
    'X-API-Key': 'vhk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  const result = response.data;

  if (result.verified) {
    console.log('✓ Identity verified!');
    console.log(`Name: ${result.document_data.name}`);
    console.log(`DOB: ${result.document_data.date_of_birth}`);
    console.log(`Face match: ${result.face_match.similarity}%`);
  } else {
    console.log('✗ Verification failed:', result.error);
  }
})
.catch(error => {
  console.error('API error:', error.response.data);
});

PHP

<?php
// Read and encode images
$selfieB64 = base64_encode(file_get_contents('selfie.jpg'));
$idFrontB64 = base64_encode(file_get_contents('id_front.jpg'));

// Call VerifyIdentity API
$ch = curl_init('https://app.verifyhuman.io/api/identity/v1/submit');
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([
    'selfie_b64' => $selfieB64,
    'id_front_b64' => $idFrontB64,
    'name' => 'John Doe',
    'date_of_birth' => '1990-05-15'
]));

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

$result = json_decode($response, true);

if ($result['verified'] ?? false) {
    echo "✓ Identity verified!\n";
    echo "Name: " . $result['document_data']['name'] . "\n";
    echo "DOB: " . $result['document_data']['date_of_birth'] . "\n";
    echo "Face match: " . $result['face_match']['similarity'] . "%\n";
} else {
    echo "✗ Verification failed: " . ($result['error'] ?? 'Unknown error') . "\n";
}
?>

🔒 Privacy & Security

Zero-Storage Policy

⚠️ PRIVACY GUARANTEE: VerifyIdentity never stores verification media or biometric data.

What We Store

We only retain minimal metadata for compliance:

What We Never Store

Security Best Practices

  1. Never expose API keys in frontend code
  2. Use HTTPS for all API calls
  3. Implement server-side validation for production apps
  4. Rotate API keys periodically (every 90 days)
  5. Store verification IDs only - never raw images

📊 Pricing & Credits

What Counts as a Verification:

Upgrade: Need more credits? View Pricing

❓ FAQ

Technical Questions

Q: What ID documents are supported?

A: We support driver licenses, passports, and national identity cards from 190+ countries. Most government-issued photo IDs work.

Q: How accurate is face matching?

A: Our AI model provides 95%+ accuracy for face matching. Confidence scores above 90% are considered verified.

Q: Can I verify without user-provided data fields?

A: Yes! The name, date_of_birth, and address fields are optional. OCR will extract data from the ID regardless. These fields are only used for additional validation if you want to confirm user input matches ID data.

Q: How long does verification take?

A: VerifyIdentity typically completes in 3-5 seconds:

Q: What image formats are supported?

A: JPEG and PNG. Images should be base64-encoded. Maximum 10MB per image.

Business Questions

Q: How much does VerifyIdentity cost?

A: Each verification costs 30 credits, regardless of pass/fail. New accounts get 50 free credits. After that, credits are available via subscription plans or prepaid packages.

Q: Can I get a refund if verification fails?

A: No. Credits are consumed whether verification passes or fails, as AI processing occurs regardless of the outcome.

Q: What's your uptime SLA?

A: 99.9% uptime for Pro and Enterprise plans. Check status.verifyhuman.io for real-time status.

Privacy & Compliance

Q: Is VerifyIdentity GDPR/CCPA compliant?

A: Yes. We process images in-memory only and never store biometric data. Only extracted text data (name, DOB) is retained.

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 verification_id, status, and extracted text data. Never store images or biometric information.

Q: What if my database gets hacked?

A: Since VerifyIdentity doesn't store images or biometric data, there's nothing sensitive to steal. Attackers would only see verification IDs, statuses, and extracted text data.

Implementation Questions

Q: Do I need both ID front and back?

A: ID back is optional but recommended. Many IDs (like driver licenses) have additional information on the back that improves verification accuracy.

Q: Can I customize the verification flow?

A: Yes. Use the VerifyIdentity Wizard to customize branding, messages, and behavior. For advanced customization, use the API directly.

Q: Can users upload pre-existing photos?

A: Not recommended. Liveness detection works best with fresh selfies taken during verification. Pre-existing photos can be spoofed.

🔧 Error Handling

Common Error Responses

Insufficient Credits:

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

Invalid API Key:

{
  "error": "This endpoint requires a VerifyIdentity API key",
  "status": "ERROR",
  "hint": "Generate a unified API key with verifyidentity scope (vhk-...) from your dashboard"
}

Poor Image Quality:

{
  "error": "Image quality too low for face detection",
  "status": "ERROR",
  "hint": "Ensure good lighting and clear face visibility"
}

OCR Failed:

{
  "success": false,
  "verified": false,
  "error": "Unable to extract text from ID document",
  "hint": "Ensure ID image is clear, well-lit, and not blurry"
}

📞 Support

Need help with VerifyIdentity?