Admiin API docs

Monitoring

Turn on ongoing monitoring for a customer, read the alerts it raises and keep the evidence behind them.

Before you begin

You need an access token and your partner id. See Authentication and first request.

X-Partner-Id is required on every route below and is checked against the OAuth principal.

For Demo business and individual examples, see Demo test data. A lookup result does not enrol its returned people in monitoring; complete an eligible individual verification first.

Availability by environment

Monitoring API routes are available to every authenticated partner in Demo and Production. No separate partner activation is required. Enablement is asynchronous: in Production, treat a subject as monitored only after its coverageState becomes COVERED or you receive monitoring.subscription.enabled.

Demo uses the screening service's test environment, which does not currently confirm ongoing monitoring enrolment. An enable request can be accepted and later move to ERROR. Use POST /v1/verifications/{verificationId}/monitoring/simulate to exercise subscription and alert flows, and use the Developer page's signed test webhooks to test your receiver.

The two products

Monitoring covers two separate things. Every route takes a product and they do not overlap.

product What it watches
INDIVIDUAL_AML A verified individual, for PEP and sanctions changes.
BUSINESS_DETAILS_OWNERSHIP A business's registered details and ownership. Named after the screening service's own wording so it is never read as AML coverage.

Company and individual subjects

A company verification can monitor its people and the company. Each product has its own subjects, coverage and price.

Example: one company verification
People INDIVIDUAL_AML
Person A Person B

2 individual subjects

Company BUSINESS_DETAILS_OWNERSHIP
Company

1 organisation subject

Each person needs an eligible individual verification. Finding them in a business lookup does not enrol them in individual monitoring.

Business change alerts

An alert reports a registry event. It does not refresh ownership or rerun individual KYC. A court-action event may not involve an ownership change.

Read the alert's evidence using the same verificationId and product=BUSINESS_DETAILS_OWNERSHIP. The event includes eventType, eventDate, summary and ownershipDetailsStatus: NOT_REFRESHED. Review and classify the event without presenting the previous ownership report as current.

Opening an alert is free. A separate UBO_ONLY lookup may recheck matched people and is charged at the KYB_UBO_REPORT price in GET /v1/pricing. The current API cannot link that lookup to the alert or update its evidence. Never order it automatically when an alert arrives.

Settings and overrides

A selected setting is separate from confirmed monitoring. Business subject responses may include subscriptionStatus: UNKNOWN, PENDING_ENABLE, ENABLED, PENDING_DISABLE, DISABLED or ERROR. Keep pending and unresolved subjects visible after switching the setting off. DISABLED applies to this verification's subject; another authorised relationship may still need the shared subscription. If the field is absent, do not interpret NOT_COVERED as confirmation that a subscription ended. 

GET   /v1/verifications/{verificationId}/monitoring?product=INDIVIDUAL_AML
PATCH /v1/verifications/{verificationId}/monitoring

Include product, state and an idempotencyKey. Enabling also requires authorityConfirmed: true and the preview's opaque previewToken. Disabling does not require billing consent or a preview.

State is exact: ENABLED or DISABLED. There is no partner default, contact override or inheritance on a verification route. A new verification for the same contact starts independently.

Each product starts DISABLED. Eligible subjects are materialised only through explicitly accepted authority and are never resubmitted for KYC by preview or simulation.

Preview the cost

POST /v1/verifications/{verificationId}/monitoring/preview

Preview returns the exact command, cohort and unit price before you make the change. The opaque token binds those values to this verification and payer. Two separately enabled verifications for one contact are two disclosed service units and may each be charged.

The business preview shows the applicable currency and monthly rate. A full UTC calendar-month fee accrues after confirmed activation, without proration. Collection occurs after that month closes. Report refreshes are excluded. Existing subscriptions without recorded authority are not retrospectively charged.

Review eligibleSubjects, excludedSubjects and price.eligibleUnits before enabling. For INDIVIDUAL_AML, eligible units count people. For BUSINESS_DETAILS_OWNERSHIP, the count is normally one organisation. If the cohort, payer or price changes before the PATCH, discard the token and request a new preview.

Subjects

GET   /v1/verifications/{verificationId}/monitoring/subjects?product=INDIVIDUAL_AML
GET   /v1/verifications/{verificationId}/monitoring/subjects/{subjectId}?product=INDIVIDUAL_AML
PATCH /v1/verifications/{verificationId}/monitoring/subjects/{subjectId}

A subject is one eligible person or the bound organisation in this verification. The PATCH excludes or re-includes that subject without changing any other verification.

Always read subjectId and subjectType from the API. Do not construct them. Combine verificationId, product and subjectId when storing subject state. Excluding one person does not affect the company or the other people. Disabling a product applies to every subject for that product in the verification.

The verification settings response separates requested policy from observed coverage. policy.state: ENABLED records intent; it does not prove screening is active.

coverage.state How to handle it
FULL Every eligible subject for this product is covered.
PARTIAL Some eligible subjects are covered. Read the subject list to find the gaps.
PENDING_AUTHORITY Authority is still required for at least one subject.
PENDING_PROVIDER Activation or deactivation is still being reconciled.
ERROR Coverage cannot be relied on.
NONE or NOT_SELECTED No active coverage is established for this product.

At subject level, treat only coverageState: COVERED as confirmed coverage. EXCLUDED, PENDING_AUTHORITY, PENDING_PROVIDER, NOT_COVERED and ERROR are not covered states.

Subscription webhook events

Four events report a terminal subscription transition for one subject. The pending states in between are our own retry loop. Every event carries contactId, product and occurredAt. Full payload shapes are in Webhooks.

Subscription payloads deliberately omit subjectId. When a verification-scoped event arrives, use its verificationId and product to list the subjects again. An enabled event confirms a subject transition; it does not by itself prove the verification has FULL coverage.

Event What it means
monitoring.subscription.enabled A subject is monitored. Carries coverage when one is recorded.
monitoring.subscription.disabled A subject is no longer monitored. Refetch the subject list before describing overall verification coverage.
monitoring.subscription.coverage_mismatch A subject is screened at observedCoverage, not at requestedCoverage. Treat it as an open compliance issue, not an informational ping.
monitoring.subscription.error The subscription is failing at the screening service. No coverage is claimed and no error code is sent, because we cannot assert what is being screened while it fails. Treat the affected verification as not reliably monitored until an enabled event follows.

Alerts

GET /v1/verifications/{verificationId}/monitoring/alerts?product=INDIVIDUAL_AML
GET /v1/verifications/{verificationId}/monitoring/alerts/{alertId}?product=INDIVIDUAL_AML

An alert is raised when a monitored subject changes. Subscribe to the monitoring webhook category to be told as they arrive rather than polling. See Webhooks.

Alert webhook events

Event What it means
monitoring.alert.created A new compliance case is open against a monitored contact. A possible match to adjudicate, not a verdict.
monitoring.alert.updated An existing case changed, most often because it was adjudicated and status moved off OPEN. The category set can also widen. A case replaced by a newer case for the same subject is sent with SUPERSEDED; its supersededByAlertId names the newer case.

Both carry monitoringAlertId, contactId, product, categories and status. Verification-scoped events also carry verificationId. No name, no screening-service entity id, no article snippets or URLs and no raw match records are pushed. Fetch the alert to obtain its subjectId, then fetch the evidence through the authorised routes above.

Evidence

GET /v1/verifications/{verificationId}/monitoring/alerts/{alertId}/evidence?product=INDIVIDUAL_AML

Returns the live match evidence behind an alert: the matched entity detail that caused it to fire. This is fetched from the screening service when you call it.

Evidence is personal information. Handle and store it in line with your data-handling obligations and the partner agreement.

A successful empty evidence collection means no evidence was returned. 503 EVIDENCE_UNAVAILABLE means the evidence could not be served and must not be presented as “no matches”.

Each listing carries a groupId that points to an entry in groups. A group is one screening search. It compares the searched name, date of birth and country with the listed values and gives each a result of SAME, SIMILAR, DIFFERENT or NOT_AVAILABLE. The comparison is a guide for the reviewer, not a decision.

The evidence also carries sanctionsChecklist: the checklist a true-positive sanctions decision must acknowledge. It is live in Demo and Production. The current version is v2. The checklist records your own steps under your AML/CTF program. The sanctions decision is yours.

Actions and testing

Classifying an alert

POST /v1/verifications/{verificationId}/monitoring/alerts/{alertId}/classify

Record your decision on an alert, whether the match is your customer or not. Classification is your AML/CTF record of the review, so classify every alert you action rather than only the ones that turn out to be real.

Read the evidence first, then send product, disposition and idempotencyKey. A decision needs an evidence read by the same principal. There is no time limit. When the decision is recorded the listings are checked again. If they changed since your last read the route answers 409 EVIDENCE_STALE: fetch the evidence again, review the update and retry. If they cannot be checked it answers 503 EVIDENCE_UNAVAILABLE and records nothing, so retry with the same idempotencyKey. The reviewer is recorded from your authenticated identity.

A true-positive decision on a case whose categories include PEP takes a pepSubtype of FOREIGN, DOMESTIC, INTERNATIONAL_ORG or FORMER. It is optional for now and becomes required on the date given in the release notes. Any other decision records no class.

A true-positive sanctions decision also requires sanctionsAcknowledgement. Build it from sanctionsChecklist in the evidence response: send its checklistVersionId and the id of every item the reviewer has acknowledged. Show each item's text as served. Do not hard-code the item ids or text, because a new checklist version replaces them.

Demo simulation

POST /v1/verifications/{verificationId}/monitoring/simulate

In a non-production environment, send the required product and an action of ENROL, ALERT or BOTH. Subjects must already have been materialised by an accepted enable command.

Simulation makes no screening-service call and creates no monitoring charge. Use it to test subject states and the downstream event path. An alert and reviewable evidence appear only when the subject's existing screening or ownership results contain a relevant change. It does not prove live upstream enrolment, natural upstream events or recurring billing.