Enrol a subject in ongoing AML monitoring
POST /api/v1/aml/monitor
POST https://api.trustverify.co.uk/api/v1/aml/monitor
Screens the subject immediately and, if that screen succeeds, enrols them for daily re-screening. New matches are delivered as the aml.hit webhook event to endpoints registered with POST /api/v1/webhooks — exactly once per new match, keyed on the sanctions and PEP list entity id, so a changed caption or score does not re-alert. The enrolment screen is the baseline the daily diff runs against: if it cannot be completed the endpoint returns 503 and NO monitor is created, because a monitor with an unknown baseline would report every pre-existing listing as a new match. Metered per ACTIVE subject against the plan limit, not per screen — daily re-screens do not consume the monthly API quota. Requires the aml_monitoring feature (Growth and above). There is no per-monitor webhookUrl: supplying one is a 400.
Request body#
| Field | Type | Description |
|---|---|---|
| entityIdrequired | string | Your own reference for the subject. Re-POSTing an active one returns it unchanged. |
| namerequired | string | The name actually screened |
| entityType | string: "individual" | "business" | What the subject is: "individual", "person" for a person, matched against people; "business", "company", "organisation", "organization", "entity" for an organisation, matched against organisations. Case-insensitive. Omit it to screen a person. Any other value is a 400 and nothing is screened. |
| dateOfBirth | string | YYYY-MM-DD. Strongly recommended — narrows common-name false positives that would otherwise alert on every re-screen. |
| country | string | ISO-3166 alpha-2 |
| metadata | object |
Example request#
curl -sS -X POST 'https://api.trustverify.co.uk/api/v1/aml/monitor' \
-H "Authorization: Bearer $TRUSTVERIFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"entityId": "seller_123",
"name": "Test Person",
"entityType": "individual",
"country": "GB"
}'Responses#
200 An active monitor already existed for this entityId; returned unchanged, no new screen was run and no quota consumed
201 Monitor created; the enrolment screen completed
| Field | Type | Description |
|---|---|---|
| monitorIdrequired | string | |
| entityIdrequired | string | Your own reference for the subject |
| entityTyperequired | string: "individual" | "business" | What the subject was screened as. "business" means it was matched against organisations. |
| namerequired | string | |
| dateOfBirthrequired | string,null | |
| countryrequired | string,null | |
| statusrequired | string: "active" | "suspended" | "cancelled" | |
| suspensionReasonrequired | string,null | plan_lapsed or over_plan_limit when status is suspended |
| checkFrequencyrequired | string | |
| lastScreenedAtrequired | string,null | The last screen that actually COMPLETED. Never advanced by a failed attempt, so it bounds the window in which a new match could have appeared unnoticed. |
| lastRiskLevelrequired | string,null | |
| lastHitCountrequired | number,null | |
| consecutiveFailuresrequired | number | Consecutive failed screens. Non-zero means monitoring is currently degraded for this subject. |
| nextCheckAtrequired | string,null | |
| cancelledAtrequired | string,null | |
| createdAtrequired | string,null | |
| metadatarequired | object | |
| environmentrequired | string | |
| baselineCheckIdrequired | string | The enrolment screen, retrievable as a check and renderable as an RPT-003 report |
| baselinerequired | object | What the subject already matched at enrolment. Never alerted on. |
| baseline.hitCountrequired | number | |
| baseline.riskLevelrequired | string | |
| baseline.sanctionsMatchrequired | boolean | |
| baseline.pepStatusrequired | boolean | |
| baseline.adverseMediarequired | boolean | |
| baseline.screenedAtrequired | string | |
| alertingrequired | object | |
| alerting.eventrequired | string: "aml.hit" | |
| alerting.subscribedEndpointsrequired | number | Active webhook endpoints subscribed to aml.hit. Zero means new matches cannot be delivered. |
| alerting.warning | string | |
| quotarequired | object | |
| quota.limitrequired | number,null | null when the plan is unlimited |
| quota.activerequired | number | |
| quota.remainingrequired | number,null |