API docs · Face Terminal

Face check API

Quick start

Sign in with a work Google account to get a key. Then send a photo of the person (an ID document or any clear picture of their face) and a selfie:

curl -s https://face.unbackoffice.com/v1/face/verify \
  -H "X-API-Key: $FACE_KEY" \
  -F [email protected] \
  -F [email protected]

Auth

Send your key in the X-API-Key header on every request. Keep it on your server. Never put it in a browser or mobile app. Base URL: https://face.unbackoffice.com.

A key can call POST /v1/face/verify and POST /v1/face/flash. Nothing else.

Request · `POST /v1/face/verify`

A multipart/form-data body:

Field	Type	Required	Notes
`reference`	image file	yes	The photo to match against: an ID document page or a clear face photo. JPEG, PNG or WebP, up to 12 MB.
`selfie`	image file	yes	A selfie of the person, taken now. JPEG, PNG or WebP, up to 12 MB.
`clip`	video file	no	A live capture clip (WebM, up to 15 s) recorded with the capture script below. Needs `consent=granted`.
`challenge`	JSON string	no	The capture script's result for that clip.
`consent`	string	with a clip	`granted`: the person agreed to the live capture.

Two images give a face match and a spoof check on the selfie. A live capture adds the action check, the screen-flash check, the pulse read and the device checks. To run it in your own page, load https://face.unbackoffice.com/static/liveness.js, get a flash challenge from POST /v1/face/flash (free, single use, 2 minutes) from your server, and post the clip, the still it returns and the challenge result to /v1/face/verify.

Response

{
  "result": {
    "status": "verified",
    "verified": true,
    "reasons": [],
    "match": {"assessment": "match", "similarity": 0.86, "confidence": 0.8,
               "consistent_features": ["eye spacing", "nose bridge"], "discrepancies": []},
    "integrity": {"verdict": "authentic", "confidence": 0.8, "attack_signals": []},
    "engine": {"match": {"decision": "match", "score": 0.61},
                "pad": {"decision": "live", "live_score": 0.97}},
    "liveness": null,
    "checked_at": "2026-10-11T09:30:00Z"
  }
}

Trimmed. Real responses carry more detail per check.

Status

verified: the faces match and the selfie looks like a genuine live capture, on every check that ran.
review: something was inconclusive. reasons says what. Send it to a person.
failed: the faces look like different people, or the selfie shows signs of a photo, screen, mask or synthetic face.

Key fields

match: the face comparison: assessment (match, likely_match, inconclusive, likely_mismatch, mismatch), the features that agree and those that differ.
integrity: the capture review: verdict (authentic, review, suspect) and any attack signals.
engine: the face model's match score and the spoof model's live score, with their decisions.
liveness: with a live capture only: actions, screen flash, pulse and device results.

A result supports a human decision. It is not a certified biometric or liveness system. Review every review and failed result before you act on it.

Errors

Status	Meaning
`400`	A file is missing, or a clip was sent without consent.
`401`	Missing or invalid key, or the key was revoked.
`402`	No checks left on this key. The body says how to get more (below).
`403`	This key can't call that endpoint.
`413`	A file is too large.
`429`	Too many requests per minute, for this key or from this IP. Wait and retry.
`502` / `503`	The check could not run. The check is given back (up to 3 times a day per key). Retry shortly.

Quota

Your first key has 2 free checks. They don't expire or reset.
One check is one call to /v1/face/verify, with or without a live capture.
Invalid requests are not charged. A check that could not run is given back, up to 3 times a day per key. Flash challenges are free.
Get 5 more checks on your key for each new colleague who signs up through your referral link (on your key page).
For more, request a tier. We contact you and add the checks to your key.

When a key runs out, you get 402:

{
  "detail": {
    "error": "quota_exhausted",
    "message": "This key has no checks left. Share your referral link: ...",
    "checks_remaining": 0,
    "referral_url": "https://face.unbackoffice.com/?ref=yourcode",
    "upgrade_url": "https://face.unbackoffice.com/tiers"
  }
}

Your data

We delete the images and clips you send within 24 hours of the check. We keep the outcome (no images) for 12 months. You need a lawful basis, and usually the person's explicit consent, to send us their face. See the terms and the privacy notice.

Machine-readable spec: /openapi.json