Face Verify Developer Guide

What is Face Verify

Face Verify is Intellicheck's biometric matching capability that compares a live selfie against the portrait on a scanned ID to confirm that the person presenting the document is its rightful owner. It adds a liveness and facial-match layer on top of front-and-back document verification, helping customers detect identity theft and impersonation attempts that document checks alone can miss. The Face Verify signal requires a subscription.

How to use Face Verify

Your code must include selfie in the signals array of the /start endpoint request. The code follows a Transaction Workflow that includes a submit selfie step so that the /get-results endpoint response returns a facial.data object.

How to interpret Face Verify results

The Face Verify signal, shown as the facial object, confirms two things: that the person presenting an ID matches the photo on that ID, and that the selfie submitted is a real, live capture rather than a printed photo, a screen replay, or a mask. Face Verify performs two checks on every submitted selfie:

• Face Match (matched) — compares the selfie to the face on the ID.

• Face Liveness (isLive) — confirms the selfie is a live person.

Decisioning fields

The following diagram illustrates a Face Verify decisioning flow.

flowchart TD
    A[Read facial object] --> B{success is true?}
    B -- no --> E["Service error<br/>do not read booleans"]
    B -- yes --> C{matched AND isLive<br/>both true?}
    C -- no --> F[Face Verify failed]
    C -- yes --> P[Face Verify passed]

    classDef error fill:#FCEBEB,stroke:#A32D2D,color:#501313;
    classDef failed fill:#FAEEDA,stroke:#854F0B,color:#412402;
    classDef passed fill:#E1F5EE,stroke:#0F6E56,color:#04342C;

    class E error;
    class F failed;
    class P passed;

First, check the top-level success property. When success is false, Face Verify could not complete the check and the data object may not contain the decisioning properties. Treat this as an error rather than a result, and do not read matched or isLive.

When success is true, base your Face Verify decision on the two boolean properties shown in the following table.

Use only these properties in your decisioning logic for the facial response object. Write logic according to the following rules:

• Face Verify passes if both are true.
• Face Verify fails if either is false.

Passed example

The following facial object shows a passed Face Verify check because both isLive and matched are true.

"facial": {
  "success": true,
  "result": true,
  "message": "",
  "data": {
    "errorMessage": null,
    "isLive": true,
    "matched": true,
    "livenessScore": null,
    "livenessProbability": 1.0,
    "matchScore": 543,
    "matchProbability": null
  }
},

Failed example due to face liveness

The following facial object shows a failed face liveness check.

"facial": {
  "success": true,
  "result": true,
  "message": "",
  "data": {
    "errorMessage": null,
    "isLive": false,
    "matched": true,
    "livenessScore": null,
    "livenessProbability": 0.0,
    "matchScore": 543,
    "matchProbability": null
  }
},

In this example, isLive is false and matched is true. This means the face liveness check failed while the face match check passed. Your code should evaluate this example as a failed Face Verify check.

Failed example due to face match

The following facial object shows a failed face match check.

"facial": {
  "success": true,
  "result": true,
  "message": "",
  "data": {
    "errorMessage": null,
    "isLive": true,
    "matched": false,
    "livenessScore": null,
    "livenessProbability": 1.0,
    "matchScore": 451,
    "matchProbability": null
  }
},

In this example, isLive is true and matched is false. This means the face liveness check passed while the face match check failed. Your code should evaluate this example as a failed Face Verify check.

Error example

The following facial object shows a service error, not a verification result.

"facial": {
  "success": false,
  "result": false,
  "message": "",
  "data": {
    "errorMessage": "Face Verify could not process the image"
  }
},

In this example, success is false, so Face Verify did not complete.

The data object contains only errorMessage and none of the decisioning properties. Do not evaluate matched or isLive in this case. Handle it as an error and retry or route the transaction according to your own error-handling policy.

Properties to ignore

Certain facial properties are of limited value and should be ignored with respect to decisioning:

• The result and message properties are diagnostic. result indicates whether a data object was returned, not whether the check passed. message is typically empty.

Properties for reference only

The facial object also includes the following non-decisioning score and probability values:

• livenessScore, livenessProbability

• matchScore, matchProbability

These are raw output values from the underlying AI model for Face Verify. They are provided for reference only. Do not use them for decisioning.

When a genuine user fails

Most Face Verify failures come from image quality, not fraud. When a selfie or ID image is poor, confidence drops even for legitimate users. Guiding your users toward a clean capture reduces false rejections more than anything else. The most common issues:

• Lighting — face the main light source; avoid strong backlight, such as a window behind the user.
• Framing — center the face and keep it fully in frame, from forehead to chin.
• Stability — hold the camera steady to avoid motion blur.
• Obstructions — remove sunglasses, hats, or anything covering the eyes or face.
• ID image — capture the ID on a flat, evenly lit surface to avoid glare and shadows.

Next steps

See Face Verify Upgrade FAQ for timelines, testing options, and subscription details.
See Face Verify (facial) Response Object for the schema properties and descriptions.