Skip to Content
MYIDIIDocs

How a check works

The life of a session, who decides the result, and what you get back.

The flow

  1. Your server calls POST /v1/sessions with its secret key. We return a session with a single-use url.
  2. The person opens that url, in a pop-up over your page or as a redirect, and does the scan.
  3. Our servers decide the result. The page only ever learns whether it passed, so it can show the right screen.
  4. We send session.completed to your webhook, and the result is available at GET /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

StatusMeaning
createdThe session exists. Nobody has opened the link yet
in_progressThe person opened the link and is scanning
passedA real person was at the camera
failedWe couldn't confirm a real person after the tries allowed
expiredThe 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

  • status and score: 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.

On this page