Veris Compare

Veris Compare runs on a dedicated server separate from the main API. It accepts two face images - a captured image and a reference - and returns a match result with a 0–100 confidence score.

Technology:

• Proprietary face recognition engine optimised for accuracy across diverse skin tones and real-world lighting conditions.
• Specifically tuned for the West African market — performs well in varied indoor and outdoor lighting typical of Nigerian ID verification flows.

Privacy model:

• Images are never stored. They are deleted in the finally block of every request handler - even if the request errors.
• No image data is written to logs at any verbosity level.
• The Compare server has no direct database connection. It communicates only with api.verisinfra.com for license validation.

Typical integration pattern

Veris Compare is most commonly used alongside Veris Capture and Veris Scan in a document-to-selfie verification workflow:

1. Use Veris Scan to extract the face photo from a user's ID document (faceImageBase64 in the scan result).
2. Use Veris Capture to take a live selfie with liveness detection.
3. Send both images to Veris Compare from your backend. A confidence score above 90 is a strong match.

Use your production license key as a Bearer token. There is no separate API key for Compare.

Authorization: Bearer veris_live_regular_xxxxxxxxxxxxxxxxxxxx

Two endpoints, both perform the same comparison. Pick the one that fits your stack.

POST /v1/compare/base64

Send images as base64-encoded strings in a JSON body. Good for backends that already have images in memory or as strings.

{
  "captured_b64":  "<base64-encoded JPEG or PNG>",
  "reference_b64": "<base64-encoded JPEG or PNG>",
  "use_case":      "kyc_onboarding"   // optional — see use cases below
}

POST /v1/compare/files

Send images as multipart form data. Good for backends working with file streams or disk-based uploads.

captured   <file>   JPEG or PNG, max 5 MB
reference  <file>   JPEG or PNG, max 5 MB
use_case   <string> optional — see use cases below
threshold  <float>  optional — direct threshold override

GET /v1/compare/use-cases

Returns all available use_case values with their thresholds and descriptions. No authentication required.

GET /v1/compare/quota

Returns your current quota usage for the active billing cycle.

{
  "plan":              "regular",
  "quota_total":       10000,
  "quota_used":        258,
  "quota_remaining":   9742,
  "overage_count":     0,
  "cycle_resets_at":   "2026-04-01T00:00:00Z"
}

{
  "match":            true,
  "confidence":       91.4,
  "distance":         0.086,
  "threshold":        85,
  "use_case":         "kyc_onboarding",
  "engine":           "veris-compare-v3",
  "environment":      "production",
  "quota_remaining":  9742,
  "comment":          "Match confirmed. The same person was identified in both images...",
  "captured": {
    "face_detected":    true,
    "detection_score":  0.884,
    "pose": { "pitch": -6.0, "yaw": 5.1, "roll": -1.5 },
    "face_size_px":     480,
    "quality":          "high",
    "quality_score":    88.6
  },
  "reference": {
    "face_detected":    true,
    "detection_score":  0.872,
    "pose": { "pitch": -12.8, "yaw": 4.5, "roll": 2.3 },
    "face_size_px":     143,
    "quality":          "medium",
    "quality_score":    55.9
  },
  "flags":             ["medium_reference_quality"],
  "recommendation":   "manual_review"
}

FaceInfo object

Returned for both captured and reference. Returned with every comparison at no extra cost or call.

Flags

Recommendation

Pass use_case in every request. It sets the match threshold automatically for your scenario. Choosing the wrong preset is the most common cause of unexpected false rejections or false acceptances.

You can also override the threshold directly with "threshold": 90 (a similarity percentage) if you need custom calibration beyond the presets. Call GET /v1/compare/use-cases to retrieve the current preset values programmatically. Preset values may be tuned over time; the endpoint is the source of truth.

All error responses follow the same shape:

{
  "error":   "FACE_NOT_DETECTED",
  "message": "No face detected in the captured image."
}

Quota reset: Resets on the first day of your billing cycle - not on the 1st of the calendar month. Check your dashboard for the exact reset date.

Overage cap: Once you exceed both the included quota and the overage cap, the Compare API returns QUOTA_EXCEEDED until the next cycle. The cap is a hard ceiling: calls stop at it and you are never billed past it. Spark and Build stop at their included amount. Your base subscription is not suspended; only Compare calls are blocked.

Wallet (optional prepaid credit): Turn the wallet on in your dashboard and Compare keeps working after your included comparisons, and any overage up to the cap, are used up. Each further comparison is paid from your credit at one flat price per comparison, shown in your dashboard. The wallet is off by default, only comparisons that succeed are charged, and you can set a spending limit for each billing cycle. Your balance stays in your wallet and carries over from month to month until you use it. A comparison paid from the wallet does not count towards your plan quota.

Automatic top-up: When you turn the wallet on, automatic top-up is on too. If a card is saved on your subscription, Veris adds credit to your wallet through Paystack when the balance runs low; you choose the amount and when it happens, and you can switch it off at any time. If the wallet runs out before the top-up lands, the call returns QUOTA_EXCEEDED with wallet_reason WALLET_TOPPING_UP; retry in a few seconds. GET /v1/compare/quota includes can_consume (whether the next comparison will be served) and a wallet object with your balance, the comparisons left and topping_up.

Overage billing: Calculated at midnight on the last day of your billing cycle and charged as a one-time payment. If the charge fails, you have a 72-hour window to resolve it. After that, Compare calls are throttled to zero until payment succeeds.

Rate limits are per license key, not per account. If you run multiple apps, each has its own limit. When a limit is hit, the response is 429 RATE_LIMITED with a Retry-After header indicating when you can retry.

Complete working examples for the most common backend environments.

const fs       = require('fs');
const FormData = require('form-data');
const fetch    = require('node-fetch');

async function compareFaces(capturedPath, referencePath) {
    const form = new FormData();
    form.append('captured',  fs.createReadStream(capturedPath));
    form.append('reference', fs.createReadStream(referencePath));

    const res = await fetch('https://compare.verisinfra.com/v1/compare/files', {
        method: 'POST',
        headers: {
            Authorization: 'Bearer veris_live_regular_xxxx',
            ...form.getHeaders(),
        },
        body: form,
    });

    const data = await res.json();
    if (!res.ok) throw new Error(data.message || data.error);

    console.log(`Match: ${data.match} - Confidence: ${data.confidence}%`);
    return data;
}

async function compareFacesBase64(capturedBuffer, referenceBuffer) {
    const res = await fetch('https://compare.verisinfra.com/v1/compare/base64', {
        method:  'POST',
        headers: {
            'Authorization':  'Bearer veris_live_regular_xxxx',
            'Content-Type':   'application/json',
        },
        body: JSON.stringify({
            captured_b64:  capturedBuffer.toString('base64'),
            reference_b64: referenceBuffer.toString('base64'),
        }),
    });

    if (!res.ok) {
        const err = await res.json();
        throw new Error(err.error);
    }
    return res.json();
}

import requests
import base64

def compare_faces_base64(captured_path: str, reference_path: str) -> dict:
    with open(captured_path, "rb") as f:
        captured_b64 = base64.b64encode(f.read()).decode()
    with open(reference_path, "rb") as f:
        reference_b64 = base64.b64encode(f.read()).decode()

    response = requests.post(
        "https://compare.verisinfra.com/v1/compare/base64",
        headers={"Authorization": "Bearer veris_live_regular_xxxx"},
        json={"captured_b64": captured_b64, "reference_b64": reference_b64},
        timeout=30,
    )
    response.raise_for_status()
    data = response.json()

    print(f"Match: {data['match']} - Confidence: {data['confidence']:.1f}%")
    return data

def compare_faces_files(captured_path: str, reference_path: str) -> dict:
    with open(captured_path, "rb") as cap, open(reference_path, "rb") as ref:
        response = requests.post(
            "https://compare.verisinfra.com/v1/compare/files",
            headers={"Authorization": "Bearer veris_live_regular_xxxx"},
            files={
                "captured":  ("captured.jpg",  cap,  "image/jpeg"),
                "reference": ("reference.jpg", ref,  "image/jpeg"),
            },
            timeout=30,
        )
    response.raise_for_status()
    return response.json()

# Files endpoint
curl -X POST https://compare.verisinfra.com/v1/compare/files \
  -H "Authorization: Bearer veris_live_regular_xxxx" \
  -F "captured=@/path/to/face.jpg" \
  -F "reference=@/path/to/id_photo.jpg"

# Base64 endpoint
curl -X POST https://compare.verisinfra.com/v1/compare/base64 \
  -H "Authorization: Bearer veris_live_regular_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "captured_b64":  "'$(base64 -i face.jpg)'",
    "reference_b64": "'$(base64 -i id_photo.jpg)'"
  }'

# Check quota
curl https://compare.verisinfra.com/v1/compare/quota \
  -H "Authorization: Bearer veris_live_regular_xxxx"

Image quality directly affects match accuracy. Follow these guidelines for best results.

• Format: JPEG or PNG. JPEG is preferred for photos - smaller file sizes and equal accuracy.
• Size: Maximum 5 MB per image. For typical photos, 200 KB–2 MB is the normal range.
• Resolution: The face should be at least 80×80 pixels after cropping. Higher is better, but diminishing returns above 400×400.
• Lighting: Avoid harsh shadows or backlighting. The Veris Compare engine handles low-light reasonably well, but extreme underexposure will reduce accuracy.
• Occlusion: No glasses, hats, or masks covering the face. The model needs clear sight of the full face region.
• Angle: Front-facing is ideal. Up to ~30° yaw is tolerated. Profile shots will likely return FACE_NOT_DETECTED.
• Document photos: The face photo extracted from ID documents via Veris Scan is pre-cropped and formatted for Compare. Pass it directly to reference_b64.