--- title: "Monitor a screening" method: POST path: "/screenings/{screening_id}/monitoring" tags: ["Screenings"] --- # Monitor a screening `POST /screenings/{screening_id}/monitoring` ## Request - Base URL: `https://developers.ozav.io/v2` - URL: `https://developers.ozav.io/v2/screenings/{screening_id}/monitoring` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer Puts a screening under continuous monitoring for one year. While it is active, the subject is screened again whenever a sanctions or PEP list adds or changes an entry that could match its name, against that entry only. A new match is recorded once as an alert and sent as a `screening.monitoring_alert` webhook. Nothing is re-screened on a schedule: the check runs when a list changes. Before it starts, the subject is screened once against the full lists: a match the screening did not report (a list changed since) is alerted right away, the same way. Calling it on an active monitoring adds one more year to where it ends. Each call is charged; send an `Idempotency-Key` (with an empty JSON object `{}` as the body) to retry safely without a second charge. Only `person` and `business` screenings can be monitored. A `customer_id` screening is `422 FEATURE_NOT_AVAILABLE` (OZAV re-screens its customers on its own), and the charge is refunded. ## Path parameters - `screening_id` string, required ## Headers - `Idempotency-Key` string ## Response `200` The monitoring of the screening. - ScreeningMonitoring - `object` 'screening_monitoring', required - `screening_id` string, required - `active` boolean, required - `monitoring_until` string, date-time, nullable, required: When the monitoring ends (or ended). `null` = never monitored. - `alerts` ScreeningAlert[], required: The alerts raised, most recent first (up to 100). - `id` string, required: Opaque alert id, prefixed `ozav_sca_`. - `list_source` string, required: The list, in the vocabulary of `matches[].list_source`. - `matched_name` string, required - `strength` 'exact' | 'alias' | 'fuzzy', required - `list_entry_ref` string, required: The list entry, as in `matches[].list_entry_ref`. - `created_at` string, date-time, required ## Other responses - `202`: Accepted - a concurrent request with the same `Idempotency-Key` is still executing; the body is `{"status": "processing"}`. Retry with the same key once the original completes: a completed request replays its stored response verbatim with the original status code and the `Idempotent-Replayed: true` header. This is not the resource - check the status code before deserializing. If this `202` repeats instead of resolving, the original request's outcome is unknown and no stored result will arrive - the key stays claimed when a request fails after the resource may already have been written. Stop retrying, reconcile with a `GET` to see whether the resource exists, and use a new key if it does not. - `401`: Missing or invalid API key. - `402`: OZAV Services only (prepaid): your prepaid credit does not cover this call (code INSUFFICIENT_CREDIT). The call did not run and nothing was charged. `details` carries `balance_usd` and `price_usd`; top up in the portal (Billing) and retry. Organizations on the OZAV platform are invoiced monthly and never receive this. On `POST /decisions` and `POST /screenings`, where OZAV accepts x402 payment, the response also carries an x402 v2 challenge: the `PAYMENT-REQUIRED` header (base64 `PaymentRequired`) and the same object in `details.x402` - the price of this one call in native USDC, paid to OZAV. `accepts` lists one entry per network OZAV receives on, Polygon (`eip155:137`) first; where enabled, a second entry offers Base (`eip155:8453`). Pay on any one of them, signing for that network's USDC (the entry's `asset`); a payment whose `accepted.asset` is not the USDC of its `network` is refused with `network_or_asset_not_accepted`. Retry with the `PAYMENT-SIGNATURE` header to pay it. A payment OZAV does not accept answers `402 X402_PAYMENT_REJECTED` with `details.reason` (`amount_below_price`, `wrong_pay_to`, `network_or_asset_not_accepted`, `authorization_not_yet_valid`, `authorization_expires_too_soon`, `authorization_window_too_long`, `signature_invalid`, `authorization_already_used`, `insufficient_balance`, `settlement_refused`, `payment_malformed` or `payment_not_accepted`) and a new challenge; nothing was charged. If OZAV could not confirm the settlement, `503 X402_PAYMENT_UNAVAILABLE`: retry with the same header, it is never charged twice. A retried payment is credited only once OZAV reads, on-chain, the transaction that used the authorization moving the USDC to OZAV; when that cannot be established automatically, the `503` says the payment needs a manual check (contact support with the request id). Where OZAV also accepts MPP, the response carries an MPP challenge in `WWW-Authenticate: Payment` (method `evm`, intent `charge`, credential type `authorization`, valid for five minutes) and in `details.mpp.www_authenticate`. A credential OZAV does not accept answers `402 MPP_PAYMENT_REJECTED` with `details.reason` (the reasons above, plus `challenge_not_issued_by_ozav`, `challenge_expired` and `nonce_not_bound_to_challenge`); `503 MPP_PAYMENT_UNAVAILABLE` means retry with the same credential. - `403`: The organization lacks the entitlement (code ENTITLEMENT_REQUIRED) or the key lacks the scope (code INSUFFICIENT_SCOPE). On money-moving requests (POST /transfers, POST /wallets/{wallet_id}/transfers) a compliance hold on the customer answers with code COMPLIANCE_HOLD: the hold is reviewed and lifted on OZAV's side; retrying does not clear it. When the only hold is a pause until pending onboarding documents are received, a withdrawal answers CUSTOMER_DOCUMENTS_PENDING instead: send what `requirements` on GET /customers/{id} lists; OZAV lifts the pause after reviewing it. On OZAV Services (live without the platform's KYB), any API outside decisions, screenings, lists and self-custody wallets answers with code PRODUCTION_NOT_ACTIVATED. - `404`: The resource does not exist, is not visible to the caller, or the id was malformed for this position (see "Resource ids" under Errors). These share one status; `code` and `message` tell them apart. - `409`: Conflict (e.g. IDEMPOTENCY_KEY_REUSED). - `422`: The request is well-formed but cannot be fulfilled - e.g. a `rail` that is not served (see `Rail.x-ozav-rail-availability`). - `503`: A dependency OZAV needs (storage, a resource lookup) could not be reached, so OZAV fails closed rather than guess. Safe to retry with the same `Idempotency-Key` where the operation accepts one. --- [API](https://skmtc.dev/ozav/apis/ozav-api.md) - [All operations](https://skmtc.dev/ozav/apis/ozav-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ozav/apis/ozav-api/revisions/4133dc2109d7?raw)