> ## Documentation Index
> Fetch the complete documentation index at: https://developer.verilock.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Active Liveness

> Multi-frame liveness detection with head turn, smile, and blink challenges.

Active Liveness adds interactive challenges during the selfie step -- requiring the user to turn their head, smile, and blink -- to provide stronger anti-spoofing protection than passive liveness alone.

## Passive vs Active Liveness

| Feature                | Passive Liveness    | Active Liveness                           |
| ---------------------- | ------------------- | ----------------------------------------- |
| User action            | None (single photo) | Head turns, smile, blink                  |
| Frames analyzed        | 1                   | 8 -- 12                                   |
| Spoof resistance       | Standard            | High                                      |
| Detects printed photos | Yes                 | Yes                                       |
| Detects screen replay  | Limited             | Yes                                       |
| Detects 3D masks       | Limited             | Yes                                       |
| User friction          | Very low            | Low -- moderate                           |
| Best for               | Low-risk onboarding | Regulated industries, high-value accounts |

## How It Works

<Steps>
  <Step title="Challenge prompt">
    The user is shown a series of on-screen prompts: turn head left, turn head right, smile, and blink. The order is randomized per session.
  </Step>

  <Step title="Multi-frame capture">
    The SDK captures 8-12 frames during the challenge sequence, analyzing pose variation and expression changes.
  </Step>

  <Step title="Scoring">
    Each frame is evaluated for pose angle, expression detection, and texture analysis. The scores are aggregated into a final liveness result.
  </Step>

  <Step title="Result">
    The session receives a liveness score (0-100) and a pass/fail determination based on the configured threshold.
  </Step>
</Steps>

## Configuration

Enable active liveness in the **Dashboard > Workflows > Liveness Settings**, or set it per session via the API:

```json theme={null}
{
  "profile": {
    "steps": ["document", "selfie"],
    "liveness_mode": "active"
  }
}
```

| Field                 | Type    | Default   | Description                                                       |
| --------------------- | ------- | --------- | ----------------------------------------------------------------- |
| `liveness_mode`       | string  | `passive` | `passive` or `active`                                             |
| `liveness_threshold`  | integer | `75`      | Minimum score to pass (0-100)                                     |
| `liveness_challenges` | array   | all       | Subset of challenges: `head_left`, `head_right`, `smile`, `blink` |

### Example: Custom Challenges

```json theme={null}
{
  "profile": {
    "steps": ["document", "selfie"],
    "liveness_mode": "active",
    "liveness_threshold": 80,
    "liveness_challenges": ["head_left", "head_right", "blink"]
  }
}
```

## Scoring Breakdown

The active liveness score is composed of two primary factors:

| Factor                   | Weight | Description                                                                             |
| ------------------------ | ------ | --------------------------------------------------------------------------------------- |
| **Pose variation**       | 50%    | Measures actual head movement across frames. Higher variation indicates genuine motion. |
| **Expression variation** | 50%    | Detects expression changes (smile, blink). Ensures the user is responding to prompts.   |

### Score Thresholds

| Score     | Interpretation                                   |
| --------- | ------------------------------------------------ |
| 90 -- 100 | Very high confidence of a live person            |
| 75 -- 89  | High confidence -- default pass threshold        |
| 50 -- 74  | Moderate confidence -- may warrant manual review |
| 0 -- 49   | Low confidence -- likely spoofed                 |

## API Response

The session detail response includes the `liveness_mode` field and active liveness data:

```json theme={null}
{
  "id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "approved",
  "selfie": {
    "liveness_mode": "active",
    "liveness_score": 92.5,
    "liveness_passed": true,
    "liveness_threshold": 75,
    "challenges_completed": ["head_left", "head_right", "smile", "blink"],
    "frames_captured": 10,
    "pose_variation_score": 94.0,
    "expression_variation_score": 91.0
  }
}
```

| Field                        | Type    | Description                         |
| ---------------------------- | ------- | ----------------------------------- |
| `liveness_mode`              | string  | `passive` or `active`               |
| `liveness_score`             | number  | Aggregated liveness score (0-100)   |
| `liveness_passed`            | boolean | Whether the score met the threshold |
| `liveness_threshold`         | integer | Threshold used for pass/fail        |
| `challenges_completed`       | array   | Challenges the user completed       |
| `frames_captured`            | integer | Number of frames analyzed           |
| `pose_variation_score`       | number  | Head movement score (0-100)         |
| `expression_variation_score` | number  | Expression change score (0-100)     |

<Warning>
  Active liveness requires the Verilock Web SDK or mobile SDKs. It is not available for API-only document upload flows.
</Warning>

<Tip>
  Start with passive liveness for low-risk use cases and upgrade to active liveness for higher-risk scenarios. You can use different liveness modes across different verification workflows.
</Tip>