API Reference

Complete reference for all API endpoints and SDK functions

API Endpoints

These endpoints require your API key and should be called from your backend.

Verify Face

Compare a reference photo with a selfie for face verification. Supports both direct file uploads and image URLs.

POST /api/v2/verify
Content-Type: multipart/form-data
Authorization: Bearer API_KEY

Request Parameters

Parameter Type Required Description
reference File Either file or URL required The reference photo file (JPEG, PNG, GIF, WebP)
reference_url String Either file or URL required URL to reference photo (must be publicly accessible)
selfie File Either file or URL required The selfie photo file (JPEG, PNG, GIF, WebP)
selfie_url String Either file or URL required URL to selfie photo (must be publicly accessible)

URL Requirements

  • Must be publicly accessible HTTPS URLs
  • Must return a valid image format (JPEG, PNG, GIF, WebP)
  • Must respond within 10 seconds
  • Maximum file size: 5MB
  • URLs must be from whitelisted domains
  • Rate limits apply to URL downloads

Response

{
  "match": true|false,
  "confidence": 95.5,
  "message": "Face match successful",
  "is_spoof": false,
  "selfie_image": "base64_encoded_optimized_selfie"
}

Error Responses

{
  "error": "Error message"
}

Common Errors

Error Message Description
Invalid URL format The provided URL is not properly formatted
Failed to download image URL is inaccessible or timed out
Domain not whitelisted URL domain is not in allowed list
File too large Image exceeds 5MB size limit
Unsupported image format Image must be JPEG, PNG, GIF, or WebP

Response

{
  "is_spoof": true|false,
  "message": "Image appears to be genuine"
}

Optimize Photo

Detect face in photo and return an optimized crop.

POST /api/v2/optimize
Content-Type: multipart/form-data
Authorization: Bearer API_KEY

Request Parameters

Parameter Type Description
photo File The photo to optimize (JPEG, PNG, GIF, WebP)

Response

{
  "success": true,
  "image": "base64_encoded_image",
  "mime_type": "image/jpeg",
  "size": 12345,
  "width": 600,
  "height": 600
}

Camera Integration

Our camera.js library provides an easy way to capture high-quality selfies with real-time face detection.

Installation

<script src="https://www.verifyfaceid.com/camera.js"></script>

Usage

// Simple usage
try {
    const photoData = await VerifyCamera.takePicture();
    if (photoData) {
        // photoData contains the base64-encoded JPEG image
        console.log('Photo captured successfully:', photoData);
    } else {
        console.log('Photo capture cancelled');
    }
} catch (error) {
    console.error('Error capturing photo:', error);
}

// Advanced usage with more control
// Initialize camera with callback for when photo is taken
const camera = new VerifyCamera((photoData) => {
    if (photoData) {
        // photoData contains base64 encoded image
        console.log('Photo captured successfully');
    }
});

// Start camera interface
await camera.start();

// Camera interface will automatically:
// - Show fullscreen camera view
// - Detect face in real-time
// - Show visual indicator when face is detected
// - Capture optimized photo when face is properly positioned
// - Call callback function with captured photo
// - Close camera interface

// Manually stop camera if needed
camera.stop();

Features

  • Real-time face detection using face-api.js
  • Automatic photo capture when face is properly positioned
  • Visual feedback with face detection indicator
  • Automatic image optimization (max 900x900, preserves quality)
  • Support for both desktop and mobile cameras
  • Handles camera permissions and errors gracefully

Error Handling

try {
    await camera.start();
} catch (error) {
    if (error.name === 'NotAllowedError') {
        console.error('Camera permission denied');
    } else if (error.name === 'NotFoundError') {
        console.error('No camera available');
    } else {
        console.error('Camera error:', error);
    }
}