Face matching and liveness

Biometric checks run in hosted verify sessions when you include them at create time. They are not available on the direct verify endpoint or the embedded document form.

What the checks do

Face matching compares a live selfie with the photo on the ID document. It shows how closely the person in front of the camera resembles the portrait on the document.

Liveness confirms a real person is present rather than a photo, screen, mask, or injected video. The hosted page guides the subject through a short live capture with on-screen prompts.

The liveness technology we use was independently tested by iBeta, a NIST accredited lab, to the ISO/IEC 30107-3 standard. It correctly identified 100% of fake faces in testing (750 out of 750 attempts) and passed at both Level 1 and Level 2.

Where biometrics run

Hosted verify sessions (SMS link): set biometrics when you create the session. That page documents defaults and supported document types.
Embedded document form: typed fields and consent only. No camera, liveness, or face match. Scores are always null on results.
Direct verify API (POST /v1/verify): you send document fields from your server. There is no selfie or liveness step and no biometric scores in the response.

End-user flow (hosted sessions with biometrics)

Open the SMS link and agree to consent (document plus biometric wording when applicable).
Photograph the ID in the browser camera (front and back for an Australian driver licence).
Enter the details printed on the document.
Complete the live selfie step: follow the oval guide and on-screen movement prompts.
Submit. The hosted page does not show issuer or score outcomes. Your backend reads the session API or webhook.

Full step-by-step screenshots are on Hosted verify sessions. While the subject is on the page, GET /v1/verify/sessions/:id may show intermediate statuses such as doc_capture_in_progress, doc_capture_accepted, and liveness_passed before processing, completed, or failed.

Hosted verify mobile screen for photographing the front of a driver licence: dashed card guide frame in the camera view, live hint to fit the card inside the frame, and auto capture (synthetic mock UI only, no real identity data). — Document capture with guide frame and live hints before the live selfie step.

Result fields (API and webhooks)

When a session finishes (or fails after biometrics ran), read result on GET /v1/verify/sessions/:id or the data object on verify_session.completed and verify_session.failed webhooks. Both use the same shape.

livenessScore: integer 0 to 100, or null when liveness did not run. Higher means stronger confidence that the selfie showed a live person. VeroID does not pass or fail this number. You choose your own minimum.
faceMatchScore: integer 0 to 100, or null when face match did not run. Higher means the document portrait and selfie look more alike. VeroID does not pass or fail this number. You choose your own minimum.
dvs.match, dvs.responseCode, and related dvs fields: issuer check on the typed document details. This is separate from the biometric scores.
verificationId: present when a verification row was created for a completed issuer match.
consentVersion and consentAttestedAt: set on embed and hosted sessions after the subject agrees (for example 2.0-biometric when biometrics are included).

{
  "success": true,
  "id": "6f1c0e3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  "status": "completed",
  "result": {
    "verificationId": "ver_abc123",
    "dvs": {
      "match": true,
      "responseCode": "Y",
      "documentType": "drivers_licence"
    },
    "livenessScore": 96,
    "faceMatchScore": 99
  }
}

Sessions without biometrics always return "livenessScore": null and "faceMatchScore": null, including every embedded form session.

When biometrics fail before the issuer check completes, status is failed and error.code may be FACE_MATCH_FAILED. Scores are still returned when the selfie was scored before the failure. See Errors.

The hosted verify UI does not expose scores to the subject. The embedded iframe posts veroid-embed events for UX only (for example complete or error with errorCode). Authoritative outcomes and scores are only on the session API and webhooks.

Help subjects complete the flow

These steps reduce retakes and abandoned sessions in production:

Use good, even lighting. Avoid strong backlighting or deep shadow on the face.
Keep the full face inside the on-screen oval during the live selfie step.
Hold the phone at about eye level, arm's length away, rather than below the chin.
Remove sunglasses, hats, and face coverings that hide the eyes or mouth.
Use a steady mobile or Wi-Fi connection before starting. Liveness needs a live video stream.
For driver licences, capture a sharp front and back photo with the card number visible.
Tell subjects the SMS link expires after eight hours so they open it promptly.

Consent copy for biometric collection is in Consent and IVS obligations and on veroid.com.au/consent.