Skip to navigation
Identity verification APIBiometric Authentication

Re-authenticate a verified person by face

Matches a live selfie against the reference enrolled when the person was verified, and answers in the same call. A liveness failure and a face that does not match are both 200 responses with authenticated: false. A hosted verification session token is also accepted in place of a key.

An unknown reference, a business, and a person who is not enrolled all answer the same 404 not_enrolled, so references cannot be probed.

Sandbox. Outside production the comparison is simulated and free. The outcome is authenticated unless sandboxOutcome pins another, or the externalUserId contains no_match, nomatch or mismatch (no match) or bio_error or bioerror (error).

Billing. Production attempts are charged per attempt. A no_match is charged, because the check ran. An attempt that fails with 502 is refunded.

Error codes

errorStatusMeaning
invalid_request400The body failed validation.
handoff_session_expired401The hosted session token has expired.
insufficient_credits402The organisation’s balance cannot cover the attempt. The message is written for the end user and does not mention credit.
environment_mismatch403The key belongs to an environment this deployment does not serve.
origin_not_allowed403The publishable key has an origin allowlist and the request origin is not on it.
ip_not_allowed403The secret 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.
not_enrolled404There is no enrolled person under that reference.
handoff_session_busy409The hosted session is busy with another request. Retry shortly.
handoff_session_used409The hosted session has already been submitted.
rate_limited429The organisation’s hourly limit was reached.
authentication_failed502The comparison could not be completed.

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

Accepts a publishable (pk_) or secret (sk_) key.

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.
externalUserIdstringRequired1-200 characters
Your reference for the person, the one their original verification was submitted with.
selfiestringRequired1-200 characters

The mediaId of a live selfie uploaded through the upload endpoint with type selfie.

livenessobjectOptional

The liveness result reported by the capture. Required in effect: without it, or without a mode, the attempt answers liveness_failed.

sandboxOutcomestringOptional<=40 characters

Pins the simulated outcome outside production: authenticated, no_match or error, or live to run the real comparison on a development key. Ignored on live keys.

Response

The attempt ran. Read authenticated for the outcome.

authenticatedboolean
True only when the person passed liveness and the selfie matched their enrolled reference.
statusenum

authenticated, no_match when the faces did not match, or liveness_failed when the liveness result did not pass.

Allowed values:
confidencedouble or null
The similarity score on a 0 to 100 scale. Null when no comparison ran.
liveboolean
Whether the liveness result was accepted.
attemptIdstring
The id of this attempt, for your records.
tokenstringOptional

A single-use proof token, present only when authenticated is true. Your backend redeems it within 30 minutes to trust a result that came from a browser or app.

Errors

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