> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Liveness Detection and Facial Biometrics in Identity Link

> Understand how anti-spoofing liveness detection works in the FULL FLOW and how to interpret biometric verification results.

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](/en/identity-link/links#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:

1. **Facial anti-spoofing**: detects impersonation attempts using photos, videos, masks, or screens.
2. **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

```bash theme={null}
curl -X GET https://api.identity.vu-one.com/api/v1/health/status
```

### Example response

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

## Accessing the selfie frames

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

```bash theme={null}
# 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}`.

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

<Note>
  `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.
</Note>

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

<Note>
  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.
</Note>


## Related topics

- [Create and Manage Verification Links](/en/identity-link/links.md)
- [Read KYC Results from Identity Verifications](/en/identity-link/kyc.md)
- [Identity Link API: Integration Guide](/en/identity-link/introduction.md)
- [Face Analysis](/en/vucs/face-analysis/introduction.md)
- [VU Cloud Services](/en/vucs/introduction.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.