API Reference

Authentication

All API requests require an API key sent via the Authorization header. API keys are generated from the customer dashboard after signing up.

Step-by-step

1. Create a TRE Faceverify account
2. Log in to the dashboard
3. Navigate to API Keys in the sidebar
4. Click Create Key and give it a name (e.g. "Production")
5. Copy the generated key — it is shown only once
6. Use the key in your API requests as shown below

Authorization: Bearer TREfvyour_api_key_here

Verify Face

Compare two face images and determine whether they depict the same person.

POST /api/v1/verify-face

Request

multipart/form-data

Response (success)

{
  "success": true,
  "match": true,
  "similarity": 0.94,
  "confidence": "very_high",
  "quality": {
    "image1": "good",
    "image2": "good"
  },
  "credits_used": 1,
  "remaining_credits": 42,
  "processing_time_ms": 245,
  "request_id": "req_abc123def456"
}

Response fields

Batch Verify

Submit multiple image pairs in a single request.

POST /api/v1/batch/verify-face

Request format

multipart/form-data

Pairs metadata example

[
  {
    "id": "pair_1",
    "image1_field": "pair_1_image1",
    "image2_field": "pair_1_image2"
  },
  {
    "id": "pair_2",
    "image1_field": "pair_2_image1",
    "image2_field": "pair_2_image2"
  }
]

Response

{
  "success": true,
  "batch_id": "batch_abc123",
  "total": 2,
  "completed": 2,
  "credits_used": 2,
  "remaining_credits": 98,
  "results": [
    {
      "id": "pair_1",
      "success": true,
      "match": true,
      "similarity": 0.91,
      "confidence": "very_high",
      "credits_used": 1
    },
    {
      "id": "pair_2",
      "success": false,
      "error": "NO_FACE_FOUND",
      "credits_used": 0
    }
  ]
}

Code Examples

cURL

curl -X POST https://api.faceverify.io/api/v1/verify-face \
  -H "Authorization: Bearer TREfvyour_api_key" \
  -F "[email protected]" \
  -F "image2=@id_photo.jpg"

Python

import requests

url = "https://api.faceverify.io/api/v1/verify-face"
headers = {"Authorization": "Bearer TREfvyour_api_key"}
files = {
    "image1": open("selfie.jpg", "rb"),
    "image2": open("id_photo.jpg", "rb"),
}

resp = requests.post(url, headers=headers, files=files)
result = resp.json()

print("Match:", result["match"])
print("Similarity:", result["similarity"])
print("Confidence:", result["confidence"])

Node.js

const FormData = require("form-data");
const fs = require("fs");

const form = new FormData();
form.append("image1", fs.createReadStream("selfie.jpg"));
form.append("image2", fs.createReadStream("id_photo.jpg"));

const resp = await fetch(
  "https://api.faceverify.io/api/v1/verify-face",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer TREfvyour_api_key",
      ...form.getHeaders(),
    },
    body: form,
  }
);

const result = await resp.json();
console.log("Match:", result.match);

Live API Tester

Choose a predefined scenario below to see how the API responds. Enter your API key to run a live test against the actual endpoint.

Same personDifferent peopleInvalid image (no face)

Two images of the same person. The API should return match: true with high similarity.

Image 1

Image 2

Expected response

{
  "success": true,
  "match": true,
  "similarity": 0.94,
  "confidence": "very_high",
  "credits_used": 1,
  "remaining_credits": 42,
  "processing_time_ms": 245,
  "request_id": "req_live_demo_001"
}

Your API key (optional — for a live test)

Run live test

Error Codes

Errors return a 4xx or 5xx status code with a JSON body.

Credits & Limits

Credits are only consumed when a valid match or no-match decision is produced. Failed validations (invalid image, no face found, etc.) do not cost credits.

Webhooks

Webhooks let you receive event notifications via HTTP callbacks. Configure them from the dashboard.

Each webhook request includes an X-TRE Faceverify-Signature header containing an HMAC-SHA256 signature of the payload. Verify this signature using your webhook secret to confirm the request is genuine.

Getting Started

Ready to integrate? Here is the quick path:

1. Create an account to receive free test credits
2. Log in and generate an API key
3. Use the code examples above to make your first verification
4. Monitor usage from the dashboard
5. Purchase credits when you need more