Liveness Detection and Facial Biometrics in Identity Link

Liveness detection is a security check that confirms the person in front of the camera is real and present at the moment of verification. In VU Identity Link, liveness runs automatically inside the FULL FLOW, comparing the face captured live against the photo on the document presented.

When liveness runs

Facial biometrics are included only in the FULL FLOW link type. If you create an ID ONLY link, the user captures the front and back of the document and nothing else — no liveness.

Flow type	Document capture	Liveness
`FULL FLOW`	Yes	Yes
`ID ONLY`	Yes	No

Adaptive branch: selfie only

Since version 2.2.0, a FULL FLOW link with adaptive flow can resolve to one of two branches for a customer who has verified before:

Branch (`method`)	What the user does
`DOCUMENT`	Full flow: document + liveness
`FACE`	Liveness only, without repeating the document capture

The branch is resolved server-side and persisted once. Read it from GET /verifications/{id}/status?include=operationGuid, in the method field. Liveness runs in both branches: what the FACE branch skips is the document capture, never the biometric check.

Anti-spoofing in Identity Link

The system applies anti-spoofing checks in two layers:

Facial anti-spoofing: detects impersonation attempts using photos, videos, masks, or screens.
Document anti-spoofing: verifies that the captured document is not a photo of a screen or a printed copy.

Whether these checks are active depends on your company configuration. Query the health endpoint to see the state of each service.

Anti-spoofing service status

curl -X GET https://api.identity.vu-one.com/api/v1/health/status

Example response

{
  "auth": {
    "status": "UP"
  },
  "biometrics": {
    "status": "UP",
    "components": {
      "antiSpoofingDocServiceIndicator": {
        "status": "UP",
        "details": { "antiSpoofing-doc": "Available" }
      },
      "antiSpoofingFaceServiceIndicator": {
        "status": "UP",
        "details": { "antiSpoofing-face": "Available" }
      },
      "ping": { "status": "UP" },
      "refreshScope": { "status": "UP" },
      "sopServiceIndicator": {
        "status": "UP",
        "details": { "antiSpoofing-face": "Available" }
      }
    }
  }
}

Node	What it reports
`auth.status`	Availability of the authentication service (`UP` or `DOWN`)
`biometrics.status`	Aggregate availability of the biometrics service
`biometrics.components.antiSpoofingDocServiceIndicator`	Document anti-spoofing. Its `details` reads `Available` or `Not Available`
`biometrics.components.antiSpoofingFaceServiceIndicator`	Facial anti-spoofing
`biometrics.components.sopServiceIndicator`	SOP service
`biometrics.components.ping`	Basic connectivity with the biometric engine
`biometrics.components.refreshScope`	State of the configuration refresh

The endpoint returns 200 when the service is operational and 503 when it is not, with the same schema in both cases. If any indicator reads DOWN, verifications that depend on that service will fail until it is restored.

Interpreting results

During the FULL FLOW you receive webhook events specific to the facial registration stage:

Event	Meaning
`verification.register.successful`	Liveness completed successfully; the live face matches the document
`verification.register.failed`	Liveness failed; possible spoofing attempt or the face does not match

The final verification.successful event fires only if both the document capture and the liveness check passed every control.

The verification does not expose biometric scores or separate liveness flags. The consolidated result lives in status (success or failed); when it fails, errorMessage describes the cause. Use the granular webhook events to know at which stage the failure occurred.

Accessing the selfie frames

You can retrieve the images captured during liveness through the image endpoints:

# List every image of a verification
curl -X GET https://api.identity.vu-one.com/api/v1/verifications/6ba7b810-9dad-11d1-80b4-00c04fd430c8/images \
  -H "Authorization: Bearer <token>"

# Get a specific image by its ID
curl -X GET https://api.identity.vu-one.com/api/v1/verifications/images/3b4c5d6e-7f80-91a2-b3c4-d5e6f7081920 \
  -H "Authorization: Bearer <token>"

The identifiers live in the verification’s images object: addFront and addBack are the document faces, and the register array holds the selfie frames taken during liveness — useful for manual audit or reviewing borderline cases.

Company-level anti-spoofing configuration

Your company’s antiSpoofing flag controls whether anti-spoofing checks are active. It is a VU-managed setting and read-only for the API: it is exposed inside the company block of GET /links/{id}.

curl -X GET https://api.identity.vu-one.com/api/v1/links/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <token>"

PATCH /users/me/company does not accept antiSpoofing. The company settings you can modify are name, color, logo, linkConfig, and verificationConfig. To change the anti-spoofing policy, contact your VU account manager.

VU Identity Link uses liveness technology certified to iBeta Level 2, meeting the industry’s most demanding standards for presentation attack detection (PAD).

If you only need document data extraction without facial verification, always create ID ONLY links. This reduces friction for the end user in cases where biometrics are not required.

Getting Started

Core Concepts

Reference

Liveness Detection and Facial Biometrics in Identity Link

When liveness runs

Adaptive branch: selfie only

Anti-spoofing in Identity Link

Anti-spoofing service status

Example response

Interpreting results

Accessing the selfie frames

Company-level anti-spoofing configuration

​When liveness runs

​Adaptive branch: selfie only

​Anti-spoofing in Identity Link

​Anti-spoofing service status

​Example response

​Interpreting results

​Accessing the selfie frames

​Company-level anti-spoofing configuration

When liveness runs

Adaptive branch: selfie only

Anti-spoofing in Identity Link

Anti-spoofing service status

Example response

Interpreting results

Accessing the selfie frames

Company-level anti-spoofing configuration