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

# Enable or disable monitoring by entity and integration

> PATCH /entities/toggle-status-monitoring — provider-code–extensible — in the gu1 entity monitoring service for ongoing screening, with examples for patch.

```
PATCH http://api.gu1.ai/entities/toggle-status-monitoring
```

**Generic** endpoint to set whether an entity **participates** in continuous monitoring for a given `integrationCode` (server behavior depends on the code; today: **Gu1 global sanctions**).

## Authentication

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Requires **edit** permission on the entity referenced by `entityId`.

## JSON body

<ParamField body="entityId" type="string" required>
  Entity UUID (must belong to your organization).
</ParamField>

<ParamField body="integrationCode" type="string" required>
  Integration / enrichment code. **Supported today:** `global_gueno_sanctions_enrichment`.\
  Other values return **400** `UNSUPPORTED_MONITORING_INTEGRATION`.
</ParamField>

<ParamField body="active" type="boolean">
  * `true` — **include** in continuous monitoring when org and upstream allow (re-enable).
  * `false` — **exclude** (same as legacy `monitoringOptOut: true`).
    At least one of **`active`** or **`riskMatrixId`** must be sent.
</ParamField>

<ParamField body="riskMatrixId" type="string | null">
  Optional. **Gu1 global sanctions** only. UUID of a risk matrix in your org, or `null` to clear the per-subscription override (daily screening then uses the **entity** risk matrix again, same as before).
  When a UUID is set, **only that matrix** is used for rules triggered by monitoring (e.g. `trigger_monitoring_completed` after daily screening); the entity’s assigned matrix is **not** merged in for that run. Does not update `entities.riskMatrixId`.
</ParamField>

## Error Responses

| HTTP | Code (example)                       | When                                                                        |
| ---- | ------------------------------------ | --------------------------------------------------------------------------- |
| 404  | `ENTITY_NOT_FOUND`                   | Entity not in org.                                                          |
| 400  | `UNSUPPORTED_MONITORING_INTEGRATION` | No handler for `integrationCode`, or `riskMatrixId` on an unsupported code. |
| 400  | `INVALID_RISK_MATRIX`                | Matrix missing, archived, or not in org.                                    |

## Example — turn off Gu1 monitoring

```bash theme={null}
curl -sS -X PATCH "http://api.gu1.ai/entities/toggle-status-monitoring" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationCode": "global_gueno_sanctions_enrichment",
    "active": false
  }'
```

## Deprecated route

`PATCH /entities/{id}/gueno-sanctions-monitoring-opt-out` with `{ "monitoringOptOut" }` is **deprecated**; use this endpoint with `active: !monitoringOptOut`.