How a check works
The life of a session, who decides the result, and what you get back.
The flow
- Your server calls
POST /v1/sessionswith its secret key. We return a session with a single-useurl. - The person opens that url, in a pop-up over your page or as a redirect, and does the scan.
- Our servers decide the result. The page only ever learns whether it passed, so it can show the right screen.
- We send
session.completedto your webhook, and the result is available atGET /v1/sessions/:id.
Who decides
The verdict is made on our servers, never on the person's device. The browser SDK hands your page a status as a courtesy, but anything in a browser can be changed by its user. Always confirm the result on your server before you act on it.
Your secret key only ever lives on your server. The browser only sees the session url, which works once and expires after 10 minutes.
Statuses
| Status | Meaning |
|---|---|
created | The session exists. Nobody has opened the link yet |
in_progress | The person opened the link and is scanning |
passed | A real person was at the camera |
failed | We couldn't confirm a real person after the tries allowed |
expired | The link ran out before the scan finished |
passed, failed and expired are final.
Tries
One session allows up to 3 tries. If a try doesn't pass, the person sees tips (face a light, take off a hat)
and can try again, without you creating or paying for a new session. attempts on the session shows how many
were used.
What you get back
statusandscore: the score is 0 to 1, and a check passes at 0.8 or above.checks: each layer and how it went, such as the face movement and the colour light check.photo_url: live checks only. A clean still photo of the person, fetched with your secret key. Use it for your own face matching, for example against an ID photo.
See the full session object.