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

# Ambient Verification

> Continuous background monitoring of identity signals to detect post-onboarding risk changes.

Ambient Verification continuously monitors identity signals after initial verification is complete. It detects changes in risk posture -- such as new sanctions listings, document expirations, adverse media mentions, and device anomalies -- and alerts you in real time.

## Overview

Traditional KYC is a point-in-time check. Ambient Verification extends this into ongoing monitoring by periodically re-evaluating identity signals and dispatching alerts when risk changes are detected.

## Signal Types

| Signal              | Source                 | Description                                      |
| ------------------- | ---------------------- | ------------------------------------------------ |
| `sanctions_listing` | AML databases          | Person added to a sanctions or watchlist         |
| `pep_status_change` | PEP databases          | Change in politically exposed person status      |
| `adverse_media`     | Media monitoring       | Negative news articles mentioning the individual |
| `document_expiry`   | Document data          | Identity document approaching or past expiration |
| `address_change`    | Public records         | Registered address change detected               |
| `device_anomaly`    | Device fingerprinting  | Suspicious device change for a returning user    |
| `velocity_spike`    | Transaction monitoring | Unusual increase in transaction volume           |
| `credit_event`      | Credit bureaus         | Significant credit event (defaults, CCJs)        |

## Severity Levels

| Severity   | Description                               | Action                                 |
| ---------- | ----------------------------------------- | -------------------------------------- |
| `info`     | Notable change, no immediate risk         | Logged for audit trail                 |
| `warning`  | Potential risk change, review recommended | Dashboard notification                 |
| `critical` | High-risk signal, immediate action needed | Webhook alert + dashboard notification |

## Enabling Ambient Verification

Enable per session when creating or after approval:

```json theme={null}
POST /v1/sessions
{
  "profile": {
    "steps": ["document", "selfie"]
  },
  "ambient_verification": {
    "enabled": true,
    "signals": ["sanctions_listing", "pep_status_change", "adverse_media", "document_expiry"],
    "frequency": "daily"
  }
}
```

| Field                            | Type    | Default | Description                                     |
| -------------------------------- | ------- | ------- | ----------------------------------------------- |
| `ambient_verification.enabled`   | boolean | `false` | Enable ambient monitoring                       |
| `ambient_verification.signals`   | array   | all     | Signals to monitor                              |
| `ambient_verification.frequency` | string  | `daily` | Check frequency: `hourly`, `daily`, or `weekly` |

## API: Trigger an Ambient Check

Run an on-demand ambient check for a specific session:

```bash theme={null}
POST /v1/sessions/{id}/ambient-check
```

```json theme={null}
{
  "signals": ["sanctions_listing", "adverse_media"]
}
```

### Response

```json theme={null}
{
  "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "check_id": "amb_x1y2z3w4",
  "status": "completed",
  "alerts": [
    {
      "signal": "adverse_media",
      "severity": "warning",
      "title": "Adverse media mention detected",
      "description": "News article published on 2026-03-17 mentions the individual in connection with a regulatory investigation.",
      "source": "Financial Times",
      "detected_at": "2026-03-18T10:00:00Z"
    }
  ],
  "no_alerts_signals": ["sanctions_listing"],
  "checked_at": "2026-03-18T10:00:05Z"
}
```

## API: List Ambient Signals

Retrieve all ambient alerts for a session:

```bash theme={null}
GET /v1/sessions/{id}/ambient-signals?severity=critical&page=1
```

| Parameter  | Type    | Default | Description                                |
| ---------- | ------- | ------- | ------------------------------------------ |
| `severity` | string  | all     | Filter by `info`, `warning`, or `critical` |
| `signal`   | string  | all     | Filter by signal type                      |
| `since`    | string  | --      | ISO 8601 timestamp to filter from          |
| `page`     | integer | `1`     | Page number                                |
| `per_page` | integer | `20`    | Results per page                           |

### Response

```json theme={null}
{
  "data": [
    {
      "id": "alert_a1b2c3d4",
      "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "signal": "sanctions_listing",
      "severity": "critical",
      "title": "Added to OFAC SDN list",
      "description": "Individual added to the OFAC Specially Designated Nationals list on 2026-03-17.",
      "source": "OFAC",
      "acknowledged": false,
      "detected_at": "2026-03-18T04:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}
```

## Response Fields

| Field          | Type    | Description                             |
| -------------- | ------- | --------------------------------------- |
| `id`           | string  | Alert identifier                        |
| `session_id`   | string  | Associated session ID                   |
| `signal`       | string  | Signal type that triggered the alert    |
| `severity`     | string  | `info`, `warning`, or `critical`        |
| `title`        | string  | Short alert title                       |
| `description`  | string  | Detailed description of the finding     |
| `source`       | string  | Data source that produced the alert     |
| `acknowledged` | boolean | Whether the alert has been acknowledged |
| `detected_at`  | string  | ISO 8601 timestamp of detection         |

## Webhook: ambient.alert

When a critical or warning-level signal is detected, an `ambient.alert` webhook is dispatched:

```json theme={null}
{
  "event": "ambient.alert",
  "data": {
    "alert_id": "alert_a1b2c3d4",
    "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "signal": "sanctions_listing",
    "severity": "critical",
    "title": "Added to OFAC SDN list",
    "description": "Individual added to the OFAC Specially Designated Nationals list on 2026-03-17.",
    "source": "OFAC",
    "detected_at": "2026-03-18T04:00:00Z"
  },
  "timestamp": "2026-03-18T04:00:01Z",
  "webhook_id": "wh_evt_amb_9f8e7d6c"
}
```

<Note>
  Only `warning` and `critical` severity alerts trigger webhooks. `info` level signals are logged but do not generate webhook events.
</Note>

<Warning>
  Ambient Verification runs on approved sessions only. Monitoring stops automatically if a session is later revoked or the associated credential is invalidated.
</Warning>

<Tip>
  Start with `daily` frequency for most use cases. Use `hourly` for high-risk accounts or regulated environments that require near-real-time monitoring.
</Tip>