> For the complete documentation index, see [llms.txt](https://manual.personr.co/api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-verification-results/setting-up-a-webhook/aml-match-webhook.md).

# AML match webhook

Get notified when ongoing AML monitoring finds a new sanctions, PEP or adverse media match on an approved entity.

Ongoing AML monitoring re-screens approved entities against global sanctions, watchlist, PEP and adverse media sources. When a re-screen finds a match the entity didn't have before, we save it to the entity's AML results, flag the entity for review in the dashboard and send this webhook.

{% hint style="info" %}
Monitoring is set per KYB flow and is off by default. Turn it on in the flow's settings under **Ongoing AML monitoring**, and choose how often to re-screen: daily, weekly or monthly (the default). It is sent to the same endpoint, with the same token in the header, as the [Setting up a webhook](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-verification-results/setting-up-a-webhook.md).
{% endhint %}

#### When it is sent

* Monitoring starts when an entity in a monitored flow is reviewed. The first re-screen runs one interval later (for example, 30 days for monthly).
* Turning monitoring on for an existing flow schedules every reviewed entity in it. Changing the frequency reschedules them.
* The webhook is sent once per re-screen that finds at least one **new** match. Matches the entity already has don't trigger it again.
* The entity's status and `reviewAnswer` don't change. Review the match and decide what to do.

#### Webhook Response

```json
{
  "event": "entity.aml_match",
  "applicantId": "1725329761404x0000000000000",
  "sourceKey": "Example Source Key",
  "externalUserId": "[\"user_123\"]",
  "amlMatchCount": "2",
  "alertTopics": "[\"role.pep\"]",
  "screenedAt": "2026-12-08T03:17:11.881Z",
  "nextScreeningAt": "2027-01-07T03:17:11.881Z",
  "sentAt": "2026-12-08T03:17:24.349Z"
}
```

| Field             | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| `event`           | Always `entity.aml_match`                                  |
| `applicantId`     | The entity's ID                                            |
| `sourceKey`       | The source key you set when creating the entity, or `null` |
| `externalUserId`  | A JSON-encoded string of your external user IDs            |
| `amlMatchCount`   | Total AML matches stored for the entity, as text           |
| `alertTopics`     | A JSON-encoded string of the entity's AML categories       |
| `screenedAt`      | When the re-screen ran (ISO 8601, UTC)                     |
| `nextScreeningAt` | When the next re-screen is scheduled (ISO 8601, UTC)       |
| `sentAt`          | When the webhook was sent (ISO 8601, UTC)                  |

When you receive it, call [Retrieving AML results](https://manual.personr.co/api-documentation/anti-money-laundering/retrieving-aml-results.md) to get the matches. `api-entity-status` also returns `amlMonitoringAlert: true` until someone marks the alert as reviewed in the dashboard.

{% hint style="info" %}
**Sandbox.** In a sandbox workspace, re-screens use the sandbox AML mock, so an entity whose name contains `pep`, `sanction` or `adverse` returns a match. Re-screens aren't billed.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://manual.personr.co/api-documentation/entity-results/retrieving-entity-verification-results/setting-up-a-webhook/aml-match-webhook.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
