Sanctions monitoring API: create and manage repeat checks

Use monitors:write to create or manage a monitor and results:read to read its health, events and resulting screenings. Set MONITOR_REQUEST_KEY to a new UUID and persist the request. name is the monitor label; subject.name is the identity being checked. Both are required. Select exactly one of sources or package.

HTTP 201 returns data.id, name and status active. Save data.id as MONITOR_ID. active means scheduling is enabled; creation queues the initial screening asynchronously and does not guarantee an initial result. The create body does not accept retention, reference, intervalHours or runNow. Retention is standard; the initial interval is the policy’s approved cadence or 24 hours without a policy.

curl --fail-with-body "https://www.sanctionskit.com/api/v1/monitors" \
  -H "Authorization: Bearer $SANCTIONSKIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $MONITOR_REQUEST_KEY" \
  --data '{
  "name": "Synthetic customer monitoring",
  "subject": {
    "name": "Alex Morgan",
    "entityType": "person",
    "birthDate": "1984"
  },
  "package": "sandbox@1"
}'

GET /monitoring?monitorId=ID returns data.items, nextCursor and the capacity forecast. Find your monitor in items and inspect status, health, revision, lastAttemptAt, lastSuccessfulAt, lastErrorCode, lastScreeningId and nextRunAt. lastScreeningId can be null before the first successful run. An empty items array does not mean a healthy no-match.

lastErrorCode and an event’s errorCode are public diagnostic codes, not screening outcomes. Handle documented business codes; temporarily_unavailable indicates a temporary service failure and screening_failed is the generic fallback. Keep unknown future codes in a failed or incomplete state. A null code alone does not prove success; use health and lastSuccessfulAt.

Use GET /results/{lastScreeningId} for retained evidence. GET /monitors and GET /monitors/{id} are compact resources using last_screening_id and next_run_at; the richer /monitoring resource uses lastScreeningId and nextRunAt. Do not mix the two response contracts.

curl --fail-with-body "https://www.sanctionskit.com/api/v1/monitoring?monitorId=$MONITOR_ID&limit=25" \
  -H "Authorization: Bearer $SANCTIONSKIT_API_KEY"

PATCH /monitoring/{id} controls scheduling. Read the current revision first, then send expectedRevision and at least one of status (active or paused), intervalHours (6, 24 or 168), or runNow:true. Include a fresh Idempotency-Key for the intended mutation. Reuse that key and identical body after an uncertain response.

The example pauses revision 1; replace 1 with the returned current revision. To resume use status active. To queue a check on an active monitor use runNow:true. Policy-backed monitors must retain the approved interval. The success data contains id and updated:true; reload /monitoring for its new revision and health. Queued work is not a completed screen. A 409 stale_revision requires reloading and reconsidering the change with a new operation key.

curl --fail-with-body "https://www.sanctionskit.com/api/v1/monitoring/$MONITOR_ID" \
  -X PATCH \
  -H "Authorization: Bearer $SANCTIONSKIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $CONTROL_REQUEST_KEY" \
  --data '{
  "expectedRevision": 1,
  "status": "paused"
}'

PATCH /monitors/{id} replaces the saved name, subject and coverage selection, with optional policy/counterpartyId and required expectedRevision. It is not a partial subject patch: send the full intended monitor definition and Idempotency-Key. Read the current saved request from /monitoring first. An update queues screening; a paused monitor must be resumed to run.

DELETE /monitors/{id} stops the monitor and clears its saved request. The response has data.id and status deleted. Repeating deletion for the same retained deleted ID is safe. Historical screening evidence follows its retention policy; deleting a monitor does not erase completed results or their usage.

GET /monitoring/inbox accepts status, kind, monitorId, limit and cursor and returns data.items plus nextCursor. Both /monitoring and its inbox use a default limit of 20 and maximum of 25. GET /monitoring/inbox/{id} returns one event. An event identifies monitorId, screeningId, previousScreeningId, caseId, kind, status and retained changes. Null screening references are valid for failures that did not create a result.

Use currentEvidenceAvailable and previousEvidenceAvailable when present; a missing/expired baseline does not invalidate a new result. The dashboard’s event acknowledgement is a human-only operation; API keys can read events but cannot acknowledge human review. Acknowledging an event never closes a case. Webhooks can signal new events using opaque IDs; retrieve the event to inspect its detail.

curl --fail-with-body "https://www.sanctionskit.com/api/v1/monitoring/inbox?status=unread&limit=25" \
  -H "Authorization: Bearer $SANCTIONSKIT_API_KEY"

A monitor belongs to one organization and environment. Its saved subject must remain available for future checks. Stopping and deleting the monitor clears that request; historical screening evidence follows its separate retention policy.

Health distinguishes pending, healthy, overdue and failed checks. GET /monitoring accepts monitorId for a direct lookup or q for a label search. Use the current revision and retry controls in step 3 after resolving the cause. Resume and retry revalidate source coverage and approved policy; a queued retry is not a completed screening.

Governed no-match rescreens renew the monitor’s case when fresh evidence requires external checks. Earlier completed checks remain historical. Administrators may opt into monitoring and overdue email notifications in organization settings; the inbox remains the place to inspect the event and linked review.

Qualified source changes schedule full rescreens alongside the selected six-hour, daily, or weekly interval. Relevant changes to match evidence, engine, or policy can reopen a dismissed case. Use the monitoring inbox to inspect changes, acknowledge events, and open the linked investigation. Editing a saved counterparty’s identity pauses its linked monitoring for review.

Each completed rescreen consumes one subject allowance. A monitor-count allowance is not unlimited screening volume. When a plan or configured cap is exhausted, further screens cannot complete until allowance is available. Treat a delayed or failed rescreen as an operational state, not evidence that nothing changed.

Request and response reference

Frequently asked questions