Skip to navigation
Identity verification APIFace Match

Compare two photos of a face

Compares two photos and answers, in the same call, whether they show the same person. The verdict is judged against the pass mark and review floor recorded for your organisation. There is no per-request threshold, so apply a stricter bar by branching on confidence.

Sandbox. Sandbox keys always return a simulated verdict (a match unless sandboxOutcome asks for another), placed inside your own thresholds. Sandbox checks are free.

Billing. Production checks are charged per comparison. A no_match is charged, because the check ran and answered. When the comparison produces no answer the charge is refunded and the response is 502 no_result, which also carries the recorded faceCheck beside the error fields.

Error codes

errorStatusMeaning
invalid_request400The body failed validation, for example consent is not true or a photo was sent in two forms or none.
same_photo400Both sides are the same media id or the same inline image.
media_unreadable400One of the uploaded photos could not be read. Send both again.
invalid_image400An inline image is not an https URL, a data URI or base64, or is too short to be a photo.
unsupported_media_type400The bytes are not a JPEG, PNG or WebP photo. The format is read from the bytes.
image_too_large400The photo is larger than 25 MB.
image_url_not_allowed400The image URL is not http(s), or resolves to a non-public address.
image_fetch_failed400The image URL could not be fetched, returned nothing, or redirected too many times.
insufficient_credits402Your balance cannot cover the check.
spot_checks_disabled403Face checks are not enabled for your organisation.
secret_key_required403A publishable key was used. This endpoint accepts secret keys only.
environment_mismatch403The key belongs to an environment this deployment does not serve.
ip_not_allowed403The key has an IP allowlist and the calling address is not on it.
organization_suspended403The organisation is suspended. The response carries reason and suspendedAt.
business_not_approved403A live key was used before the business was approved for production.
organization_not_found404The organisation behind the key no longer exists.
rate_limited429The hourly face check limit was reached. Retry later.
no_result502The comparison could not be completed. Nothing was charged.

A missing or unknown key answers 401, where error is a short sentence rather than a code.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer
Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Request

This endpoint expects an object.
consenttrueRequired
Must be true. You attest that the people shown consented to the comparison.
imageAstringOptional>=16 characters

The first photo, inline. An inline image is an https:// URL that is fetched for you, a data: URI, or base64-encoded bytes. JPEG, PNG and WebP are accepted, up to 25 MB by URL. Base64 travels inside the JSON body, which is capped at 10 MB.

imageBstringOptional>=16 characters

The second photo, inline, in the same forms as imageA.

mediaAIdstringOptional

The first photo as a mediaId from the face upload endpoint, instead of imageA.

mediaBIdstringOptional

The second photo as a mediaId from the face upload endpoint, instead of imageB.

sandboxOutcomeenumOptional

Picks the simulated verdict outside production. Sandbox keys are always simulated and default to match. Development keys run the real comparison unless an outcome is given, and live asks for the real comparison there. Ignored on live keys.

Allowed values:

Response

The comparison ran and returned a verdict.
faceCheckobject

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
502
Bad Gateway Error