> ## 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.

# Behavioral Biometrics

> Detect fraud through typing patterns, mouse movements, and device interaction analysis.

Behavioral Biometrics analyzes how users interact with their device during the verification flow -- typing cadence, mouse movements, scroll patterns, and touch gestures -- to detect bots, remote access tools, and coerced sessions.

## Signals Collected

The Verilock SDK passively collects behavioral signals during the hosted verification flow.

| Category      | Signals                                                            |
| ------------- | ------------------------------------------------------------------ |
| **Typing**    | Keystroke timing, flight time between keys, dwell time, error rate |
| **Mouse**     | Movement velocity, acceleration, curvature, click precision        |
| **Touch**     | Tap pressure, swipe speed, gesture patterns, screen contact area   |
| **Scroll**    | Scroll velocity, direction changes, momentum patterns              |
| **Session**   | Time on page, idle periods, tab switching, form interaction order  |
| **Clipboard** | Paste frequency, paste vs. typed ratio                             |

<Note>
  Behavioral data is collected transparently during the hosted flow. No additional SDK configuration is required.
</Note>

## Risk Scoring

Each session receives a behavioral risk score from **0** (no risk) to **100** (highest risk).

| Score Range | Level        | Description                                            |
| ----------- | ------------ | ------------------------------------------------------ |
| 0 -- 20     | **Low**      | Natural human interaction patterns                     |
| 21 -- 50    | **Medium**   | Minor anomalies (e.g., unusually fast form completion) |
| 51 -- 80    | **High**     | Multiple behavioral red flags                          |
| 81 -- 100   | **Critical** | Strong indicators of automation or remote access       |

## Risk Factors

| Factor              | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| `bot_like_typing`   | Typing cadence is unnaturally consistent, indicating automation            |
| `copy_paste_heavy`  | Majority of form fields were filled via clipboard paste                    |
| `remote_access`     | Mouse movements consistent with remote desktop tools (TeamViewer, AnyDesk) |
| `no_mouse_movement` | No mouse activity detected (possible headless or automated session)        |
| `rapid_completion`  | Form completed significantly faster than human average                     |
| `linear_mouse`      | Mouse moves in perfectly straight lines between targets                    |
| `coercion_signals`  | Hesitation patterns and erratic behavior suggesting user duress            |
| `tab_switching`     | Excessive tab switching during verification (copying from reference)       |

## API: Submit Behavioral Signals

If using a custom integration (not the hosted flow), submit behavioral signals directly:

```bash theme={null}
POST /v1/verify/{token}/behavioral-signals
```

```json theme={null}
{
  "signals": {
    "typing": {
      "avg_dwell_ms": 85,
      "avg_flight_ms": 120,
      "error_rate": 0.03
    },
    "mouse": {
      "avg_velocity": 450,
      "avg_curvature": 0.15,
      "click_count": 12
    },
    "session": {
      "duration_ms": 45000,
      "idle_periods": 2,
      "paste_events": 0,
      "tab_switches": 1
    }
  },
  "collected_at": "2026-03-18T10:00:00Z"
}
```

| Field                          | Type    | Description                                         |
| ------------------------------ | ------- | --------------------------------------------------- |
| `signals.typing.avg_dwell_ms`  | number  | Average key press duration in milliseconds          |
| `signals.typing.avg_flight_ms` | number  | Average time between keystrokes in milliseconds     |
| `signals.typing.error_rate`    | number  | Ratio of backspaces to total keystrokes (0-1)       |
| `signals.mouse.avg_velocity`   | number  | Average mouse speed in pixels per second            |
| `signals.mouse.avg_curvature`  | number  | Average path curvature (0 = straight, 1 = circular) |
| `signals.session.duration_ms`  | integer | Total session duration in milliseconds              |
| `signals.session.paste_events` | integer | Number of clipboard paste events                    |
| `signals.session.tab_switches` | integer | Number of tab/window switches                       |

## API Response

Behavioral biometrics data is included in the session detail response:

```json theme={null}
{
  "id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "approved",
  "behavioral_biometrics": {
    "risk_score": 12,
    "risk_level": "low",
    "risk_factors": [],
    "session_duration_ms": 45000,
    "typing_pattern": "natural",
    "mouse_pattern": "natural",
    "analyzed_at": "2026-03-18T10:00:00Z"
  }
}
```

### High-Risk Example

```json theme={null}
{
  "behavioral_biometrics": {
    "risk_score": 88,
    "risk_level": "critical",
    "risk_factors": ["bot_like_typing", "linear_mouse", "rapid_completion"],
    "session_duration_ms": 3200,
    "typing_pattern": "automated",
    "mouse_pattern": "automated",
    "analyzed_at": "2026-03-18T10:05:00Z"
  }
}
```

## Response Fields

| Field                 | Type    | Description                                |
| --------------------- | ------- | ------------------------------------------ |
| `risk_score`          | integer | Behavioral risk score (0-100)              |
| `risk_level`          | string  | `low`, `medium`, `high`, or `critical`     |
| `risk_factors`        | array   | List of detected behavioral anomalies      |
| `session_duration_ms` | integer | Total interaction duration in milliseconds |
| `typing_pattern`      | string  | `natural`, `suspicious`, or `automated`    |
| `mouse_pattern`       | string  | `natural`, `suspicious`, or `automated`    |
| `analyzed_at`         | string  | ISO 8601 timestamp of analysis             |

<Warning>
  Behavioral biometrics requires the Verilock Web SDK or mobile SDKs. API-only flows must submit signals manually via `POST /v1/verify/{token}/behavioral-signals`.
</Warning>

<Tip>
  Combine behavioral biometrics with device fingerprinting for a layered fraud detection approach. A session with both high device risk and high behavioral risk is almost certainly fraudulent.
</Tip>