# Continuous monitoring

Monitoring re-checks selected evidence on a schedule and records material risk changes.
The capability appears where the work happens:

| Task | Dashboard location |
| --- | --- |
| Enable, pause, resume, turn off, or change frequency for one customer | **Entities → Customer → Risk** |
| See what changed across customers | **Risk Intelligence → Overview** |
| Work an actionable change | **Review Queue** |
| Install or edit policy defaults | **Rules & Policies → Ongoing monitoring** |

The public API remains under `/api/v1/monitoring`.

## Policy defaults and entity overrides

A policy defines the checks, default frequency, material-change threshold and escalation behaviour.
An Entity can follow that default or use an explicit frequency override.

Supported frequencies are `hourly`, `daily`, `weekly` and `monthly`.
Every subscription response identifies:

- `frequency.effective`, the schedule currently used;
- `frequency.policyDefault`, the active policy default;
- `frequency.override`, the Entity override or `null`;
- `frequency.source`, either `policy_default` or `entity_override`.

Changing a policy default updates Entities that follow the default.
It does not silently replace an explicit Entity override.

## Entity scope and high-risk handling

`config.scope.entityTypes` defines which Entity types may use a policy version.
Values are lower case: `individual`, `business`, `wallet`, `bank_account`, `device`,
`email`, `phone` and `ip`. Omit `scope` to include every supported type.

Scope is stored with the immutable policy version. Start, bulk enrolment, policy
change and re-enable requests reject an Entity outside that version's scope.
Publishing also validates the scope against affected active subscriptions.

Scope controls eligibility, not risk severity. Use `alertLevels`, normally
`high` and `critical`, to select the risk levels that can open an alert. Use
`escalation.investigation` to choose `none`, `manual` or `automatic`
investigation handling.

## Enable monitoring

`POST /api/v1/monitoring/subscriptions`

```json
{
  "subject": { "type": "individual", "id": "ent_01" },
  "policyId": "pol_01",
  "frequency": "daily"
}
```

Omit `frequency` or send `null` to use the policy default.
Send an `Idempotency-Key` header for every mutation.

## Change policy or frequency

`PATCH /api/v1/monitoring/subscriptions/{subscriptionId}`

```json
{ "frequency": "hourly" }
```

Restore the policy default:

```json
{ "frequency": null }
```

The same endpoint accepts `policyId` when an Entity should move to another published policy.

## Pause, resume and Off

Pause and Off are different states.

| Action | Endpoint | Effect |
| --- | --- | --- |
| Pause | `POST /api/v1/monitoring/subscriptions/{id}/pause` | Keeps configuration and history. No future scheduled monitoring checks or charges run until resumed. |
| Resume | `POST /api/v1/monitoring/subscriptions/{id}/resume` | Restarts a paused subscription using its current policy and frequency. |
| Off | `POST /api/v1/monitoring/subscriptions/{id}/stop` | Permanently ends that subscription. History remains and no future checks or charges run. |

An ended subscription is immutable.
Re-enable monitoring with:

`POST /api/v1/monitoring/subscriptions/{endedSubscriptionId}/enable`

```json
{
  "policyId": "pol_01",
  "frequency": null
}
```

The response contains the linked new active subscription.
The ended record remains available for audit history.

## Retrieve state and history

`GET /api/v1/monitoring/subscriptions/{subscriptionId}` returns the current state, effective frequency, recent runs, material deltas, alerts and billing evidence.

Use the Entity view for day-to-day customer management.
Use Risk Intelligence for material changes across the portfolio, and Review Queue when a change requires action.

## Billing behaviour

Only completed billable checks consume usage.
Paused and ended subscriptions create no future scheduled monitoring checks or charges.
Historical usage remains unchanged.

## Webhooks

Start with `monitoring.delta.detected` for material customer-risk changes.
Add `monitoring.run.failed` when failed scheduled checks need an operational response.
See [Continuous Monitoring webhooks](https://trust.myaza.co/documentation/webhook-continuous-monitoring/markdown) for the exact V2 payload.