Verify endpoint

Compare one reference image with one fresh selfie. The request is strict; the response shape is fixed.

Authentication

Send an active 64-character API key in the standard Bearer header. Keep private keys on your backend whenever possible.

Authorization: Bearer YOUR_API_KEY

Request

Use multipart/form-data. Both fields are required and each field must contain exactly one file.

Both dimensions must be at least 80 pixels, an image may contain at most 40 million pixels, and the full multipart request may be at most 11 MiB. URL fields, JSON bodies, data URIs, GIF, and WebP are not accepted by v3. This keeps parsing unambiguous and avoids server-side URL fetching.

cURL example

curl https://www.verifyfaceid.com/api/v3/verify \
  -H "Authorization: Bearer $VERIFYFACEID_API_KEY" \
  -F "reference=@reference.jpg" \
  -F "selfie=@selfie.jpg"

JavaScript example

const body = new FormData();
body.append('reference', referenceBlob, 'reference.jpg');
body.append('selfie', selfieBlob, 'selfie.jpg');

const response = await fetch(
  'https://www.verifyfaceid.com/api/v3/verify',
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${apiKey}` },
    body
  }
);

const payload = await response.json();
if (!payload.success) {
  throw new Error(`${payload.error.code}: ${payload.error.message}`);
}

Successful comparison

A completed comparison is HTTP 200, whether the faces match or not.

{
  "success": true,
  "data": {
    "match": true,
    "similarity": 99.52,
    "threshold": 80
  },
  "error": null,
  "meta": {
    "api_version": "3.0",
    "request_id": "018f1ad0-…",
    "processing_ms": 412
  }
}

similarity is the AWS similarity score rounded to two decimals. When no match reaches the threshold, match is false and similarity is null; it is not presented as a made-up zero score.

{
  "success": true,
  "data": {
    "match": false,
    "similarity": null,
    "threshold": 80
  },
  "error": null,
  "meta": {
    "api_version": "3.0",
    "request_id": "018f1ad0-…",
    "processing_ms": 376
  }
}

Error envelope

Every non-preflight v3 error uses these same top-level fields. Empty details are encoded as an object, never an array.

{
  "success": false,
  "data": null,
  "error": {
    "code": "missing_image",
    "message": "The selfie image is required.",
    "details": { "field": "selfie" }
  },
  "meta": {
    "api_version": "3.0",
    "request_id": "018f1ad0-…",
    "processing_ms": 8
  }
}

Retries and request IDs

The same request ID appears in meta.request_id and the X-Request-ID response header. Include it when contacting support. Retry transient network failures and provider errors only when error.details.retryable is true, using exponential backoff. A one-second Retry-After header is supplied for the per-second rate limit.

Usage and privacy

Once Bearer authentication succeeds, a v3 request is counted once, including one that later fails image validation or provider processing. Requests rejected before authentication are not counted. Uploaded bytes are held only for request processing; this application does not persist the submitted images. The response deliberately does not echo an optimized selfie.