---
title: "AML Integration Guide"
description: "Screen customers and counterparties against AML watchlists."
collection: "guides"
slug: "aml-integration"
url: "https://naiza.ai/docs/guides/aml-integration"
markdown: "https://naiza.ai/docs/guides/aml-integration.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# AML Integration Guide

> Screen customers and counterparties against AML watchlists.

## Table of contents

- [Screen Customers and Entities](#screen-customers-and-entities)
- [Send AML Events](#send-aml-events)
- [Rules, Holds, and Outcomes](#rules-holds-and-outcomes)
- [Poll Write-Back Results](#poll-write-back-results)
- [Recommended Product Behavior](#recommended-product-behavior)

Use the AML integration when you need sanctions and AML screening for customers,
entities, counterparties, or transaction events. The integration flow is:

1. Screen a customer or entity during onboarding or review.
2. Send AML events for activity that should be evaluated by AML rules.
3. Hold or route risky events while AML evaluates them.
4. Poll by `externalEventId` when your system needs write-back status.

See the AML reference in the API Reference tab and the [Events API](https://naiza.ai/docs/api-reference/events.md)
for shared event concepts.

## Screen Customers and Entities

Call `POST /api/v1/aml/screen` when you need a synchronous screening result.
Use this for onboarding checks, periodic re-screening, and manual compliance
review.

```http
POST /api/v1/aml/screen
```

```json
{
  "inputName": "John Michael Smith",
  "externalId": "cust_123456",
  "entityType": "INDIVIDUAL",
  "inputDob": "1985-04-12",
  "inputNationality": "GB",
  "inputAliases": ["Johnny Smith"],
  "sensitivityProfile": "BALANCED"
}
```

Handle the screening decision:

- `AUTO_CLEAR` - no material match was found.
- `REVIEW` - a possible match needs investigation.
- `CONFIRMED` - the screening matched a confirmed watchlist entity.

Store the screening `id` and your `externalId` together so compliance teams can
reconcile later reviews.

## Send AML Events

Use `POST /api/v1/aml/events` when an activity should be checked by AML event
rules, such as a transaction, payment instrument change, or counterparty
update.

```http
POST /api/v1/aml/events
```

```json
{
  "eventName": "payment.completed",
  "eventCategory": "TRANSACTION",
  "externalEventId": "aml_evt_ext_123",
  "customer": {
    "externalId": "user_123456",
    "email": "user@example.com"
  },
  "sourceReportedAt": 1672520400,
  "metadata": {
    "amount": 99.99,
    "currency": "USD",
    "payment_method": "card"
  },
  "custom_fields": {
    "counterparty_country": "US"
  }
}
```

`externalEventId` should be stable and unique in your system. Use it for
polling and idempotent retries.

## Rules, Holds, and Outcomes

AML event status can be:

- `CLEAR` - no AML alert was created.
- `ALERTED` - one or more AML alerts were created.
- `HELD` - the event is waiting for a compliance workflow outcome.
- `APPROVED` - forward-compatible status for approved held activity.
- `REJECTED` - forward-compatible status for rejected held activity.

Use `HELD` when the product should pause fulfillment while compliance reviews
the event. For example, a withdrawal may stay pending until the event is
approved or rejected downstream.

## Poll Write-Back Results

Poll by `externalEventId` when your system needs the current AML result.

```http
GET /api/v1/aml/events/:externalEventId
```

```json
{
  "externalEventId": "aml_evt_ext_123",
  "status": "ALERTED",
  "alerts": [
    {
      "id": "aml_alert_123",
      "severity": "HIGH",
      "summary": "Counterparty matched a sanctions rule"
    }
  ]
}
```

## Recommended Product Behavior

- Run customer screening before account activation or high-risk product access.
- Send AML events for money movement and counterparty changes.
- Persist `externalEventId`, screening `id`, and compliance case references.
- Do not blindly retry `POST /api/v1/aml/screen` after a timeout; reconcile the
  outcome first.
- Treat `REVIEW`, `CONFIRMED`, `ALERTED`, and `HELD` as operational handoff
  points.

## Related documentation

- [Overview](https://naiza.ai/docs/guides/overview.md) — Base URL, authentication, decision types, risk scores, and rate limits.
- [Getting Started](https://naiza.ai/docs/guides/getting-started.md) — Make your first Naiza API call and verify your integration.
- [Tenant Onboarding](https://naiza.ai/docs/guides/tenant-onboarding.md) — Create tenants, invite operators, and configure webhooks.
- [Web SDK — Install & CDN](https://naiza.ai/docs/guides/web-sdk-install.md) — Install the browser SDK via CDN, self-host, and verify ingest.
- [Quick Start](https://naiza.ai/docs/guides/quick-start.md) — Common operations for events, decisions, lists, and feedback.
- [Event Monitoring](https://naiza.ai/docs/guides/event-monitoring.md) — Model product events and turn rule outcomes into decisions.
- [Integration Examples](https://naiza.ai/docs/guides/integration-examples.md) — Node.js, Python, cURL, and webhook handler examples.
- [Best Practices](https://naiza.ai/docs/guides/best-practices.md) — Production guidance for keys, idempotency, and enforcement.

---

*Source: [https://naiza.ai/docs/guides/aml-integration](https://naiza.ai/docs/guides/aml-integration) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*