---
title: "AML Screening API"
description: "Sanctions, PEP, and watchlist screening endpoints."
collection: "api-reference"
slug: "aml"
url: "https://naiza.ai/docs/api-reference/aml"
markdown: "https://naiza.ai/docs/api-reference/aml.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# AML Screening API

> Sanctions, PEP, and watchlist screening endpoints.

## Table of contents

- [Auth](#auth)
- [Endpoints](#endpoints)
- [Ingest an AML Event](#ingest-an-aml-event)
  - [Request](#request)
  - [Parameters](#parameters)
  - [Response](#response)
- [Poll an AML Event Result](#poll-an-aml-event-result)
  - [Response](#response)
- [Screen an Entity](#screen-an-entity)
  - [Request](#request)
  - [Parameters](#parameters)
  - [Response](#response)
- [Retrieve a Screening](#retrieve-a-screening)
- [Examples](#examples)
  - [cURL](#curl)
  - [JavaScript](#javascript)
  - [Python](#python)
- [Troubleshooting](#troubleshooting)

The AML API lets you screen customers or entities against sanctions and AML
watchlists, and lets you submit AML event-monitoring payloads for transaction
or counterparty workflows. It is available only to tenants with the AML
Screening product enabled.

## Auth

`x-api-key` is required. The tenant is always derived from the API key. Any
`tenantId` in the request body is ignored.

If AML Screening is not enabled for your tenant, these endpoints return `403`.

## Endpoints

- `POST /api/v1/aml/events`
- `GET /api/v1/aml/events/:externalEventId`
- `POST /api/v1/aml/screen`
- `GET /api/v1/aml/screenings/:id`

## Ingest an AML Event

Submits an AML event for tenant-scoped evaluation. The payload mirrors the
fraud event shape for integration familiarity, but AML events do not enter the
fraud events pipeline.

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

### Request

```json
{
  "eventName": "payment.completed",
  "eventCategory": "TRANSACTION",
  "externalEventId": "aml_evt_ext_123",
  "customer": {
    "externalId": "user_123456",
    "email": "user@example.com",
    "metadata": { "customer_type": "individual" }
  },
  "sourceReportedAt": 1672520400,
  "reference": "3cba8491-c0cd-44c6-8a72-78ca834db7f0",
  "metadata": {
    "amount": 99.99,
    "currency": "USD",
    "payment_method": "card"
  },
  "custom_fields": {
    "counterparty_country": "US"
  }
}
```

### Parameters

| Field | Required | Description |
| --- | --- | --- |
| `eventName` | Required by AML service | Tenant-defined AML event identifier, for example `payment.completed` |
| `externalEventId` | Required by AML service | Tenant-scoped unique id for polling and safe retries. Retries with the same id and same payload replay the stored result. The same id with a different payload returns `409`. This is not an `Idempotency-Key` header — use `GET /api/v1/aml/events/:externalEventId` to reconcile after timeouts or uncertain responses. Screening (`POST /api/v1/aml/screen`) has no equivalent key; after a timeout, reconcile via `GET /api/v1/aml/screenings/:id` if you already received a screening id, and do not blindly resubmit. |
| `eventCategory` | No | `CUSTOMER`, `ACCOUNT`, `APPLICATION`, `CONTRACT`, `TRANSACTION`, `PAYMENT_INSTRUMENT` or `COUNTERPARTY` |
| `customer` | No | Customer identifiers and optional metadata |
| `device` | No | Device identifiers, fingerprint, and optional metadata |
| `ip` | No | IP address from which the event originated |
| `userAgent` | No | User agent from the browser or application |
| `country` | No | ISO 3166-1 alpha-2 or alpha-3 country code |
| `sessionId` | No | Session identifier for tracking related activity |
| `sourceReportedAt` | No | When the event occurred in the source system, as ISO string or Unix seconds |
| `timestamp` | No | Legacy Unix timestamp in seconds. Prefer `sourceReportedAt` |
| `reference` | No | External reference ID for tracking in your system |
| `location` | No | Geographic coordinates or location context |
| `metadata` | No | Custom metadata fields with bounded depth and size |
| `custom_fields` | No | Business-specific custom fields |
| `payload` | No | Legacy fraud-event payload field, forwarded as `metadata.payload` |

### Response

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

`status` can be `CLEAR`, `ALERTED`, `HELD`, `APPROVED`, or `REJECTED`.
Current AML event results use `CLEAR`, `ALERTED`, and `HELD`; `APPROVED` and
`REJECTED` are forward-compatible write-back statuses.

## Poll an AML Event Result

Fetches the tenant-scoped AML event result by your `externalEventId`.

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

### Response

```json
{
  "externalEventId": "aml_evt_ext_123",
  "status": "ALERTED",
  "alerts": []
}
```

## Screen an Entity

Runs a synchronous screening and returns the full result, including the
decision and any watchlist matches.

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

### Request

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

### Parameters

| Field | Required | Description |
| --- | --- | --- |
| `inputName` | Yes | Full legal name of the entity to screen |
| `externalId` | Yes | Your system's identifier for the entity |
| `entityType` | No | `INDIVIDUAL`, `ORGANIZATION`, `VESSEL` or `AIRCRAFT` |
| `inputDob` | No | Date of birth (ISO 8601 date) |
| `inputNationality` | No | Nationality (ISO 3166-1 alpha-2) |
| `inputAliases` | No | Known aliases or alternate spellings |
| `inputIdDocuments` | No | Array of `{ type, value }` identity documents |
| `sensitivityProfile` | No | `CONSERVATIVE`, `BALANCED` or `LIBERAL` (defaults to tenant config) |

### Response

```json
{
  "id": "scr_abc123",
  "externalId": "cust_123456",
  "decision": "REVIEW",
  "processingMs": 142,
  "listsHit": ["OFAC_SDN"],
  "matches": [
    {
      "watchlistEntityId": "wl_987",
      "score": 92,
      "classification": "STRONG",
      "matchedName": "John Michael Smith",
      "entityName": "John M. Smith",
      "source": "OFAC_SDN",
      "sanctionReason": "Designated under E.O. 13224 for material support to a designated terrorist organization",
      "matchCity": "Damascus",
      "datesOfBirth": ["1965-03-12", "1965"],
      "scoreBreakdown": { "name": 0.95, "dob": 0.8 }
    }
  ],
  "caseId": "case_123",
  "alertId": "alert_123",
  "caseCreated": true,
  "reusedExistingCase": false
}
```

`decision` is one of `AUTO_CLEAR`, `REVIEW`, or `CONFIRMED`.

Each match also includes:

- `sanctionReason` - the detailed listing reason, or `null`
- `matchCity` - a city associated with the listed entity, or `null`
- `datesOfBirth` - all listed dates of birth; values may be full ISO dates (`yyyy-mm-dd`) or year-only (`yyyy`), for example `["1965-03-12", "1965"]`

`caseId`, `alertId`, `caseCreated`, and `reusedExistingCase` are present when
AML auto-creates a case or links the alert to an existing open case.

## Retrieve a Screening

Fetch a previously created screening by id. Results are tenant-scoped: a
screening that belongs to another tenant returns `404`.

```http
GET /api/v1/aml/screenings/:id
```

Returns the same screening result shape as `POST /api/v1/aml/screen`.

## Examples

### cURL

```bash
curl -X POST https://api.naiza.ai/api/v1/aml/screen \
  -H "x-api-key: naiza_api_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "inputName": "John Michael Smith",
    "externalId": "cust_123456",
    "entityType": "INDIVIDUAL"
  }'
```

```bash
curl -X POST https://api.naiza.ai/api/v1/aml/events \
  -H "x-api-key: naiza_api_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "payment.completed",
    "eventCategory": "TRANSACTION",
    "externalEventId": "aml_evt_ext_123",
    "customer": { "externalId": "user_123456" },
    "metadata": { "amount": 99.99, "currency": "USD" }
  }'
```

### JavaScript

```javascript
async function screen(entity) {
  const response = await fetch('https://api.naiza.ai/api/v1/aml/screen', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.NAIZA_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(entity),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message ?? error.message ?? 'AML request failed');
  }

  return response.json();
}

async function pollAmlEvent(externalEventId) {
  const response = await fetch(
    `https://api.naiza.ai/api/v1/aml/events/${encodeURIComponent(externalEventId)}`,
    {
      headers: { 'x-api-key': process.env.NAIZA_API_KEY },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message ?? error.message ?? 'AML request failed');
  }

  return response.json();
}
```

### Python

```python
import os
import requests

headers = {
    'x-api-key': os.getenv('NAIZA_API_KEY'),
    'Content-Type': 'application/json',
}

screening = requests.post(
    'https://api.naiza.ai/api/v1/aml/screen',
    headers=headers,
    json={
        'inputName': 'John Michael Smith',
        'externalId': 'cust_123456',
        'entityType': 'INDIVIDUAL',
    },
)
screening.raise_for_status()

event_result = requests.get(
    'https://api.naiza.ai/api/v1/aml/events/aml_evt_ext_123',
    headers={'x-api-key': os.getenv('NAIZA_API_KEY')},
)
event_result.raise_for_status()
```

## Troubleshooting

| Status | Meaning |
| --- | --- |
| `401` | Missing or invalid API key |
| `403` | AML Screening is not enabled for your tenant |
| `404` | Screening or AML event not found in your tenant scope |
| `422` | Missing required field or invalid AML event payload |
| `429` | Too many requests |
| `502` / `504` | The AML service was unavailable or timed out. For events, poll `GET /api/v1/aml/events/:externalEventId` with the same id you submitted. For screening, reconcile via `GET /api/v1/aml/screenings/:id` if you already received a screening id; do not blindly retry `POST /api/v1/aml/screen`. |

## Related documentation

- [API Overview](https://naiza.ai/docs/api-reference/overview.md) — Base URL, versioning, and high-level API surface.
- [Authentication](https://naiza.ai/docs/api-reference/authentication.md) — API keys, Web SDK tokens, and secure key handling.
- [Web SDK API](https://naiza.ai/docs/api-reference/websdk.md) — Browser SDK endpoints and device signal collection.
- [Events API](https://naiza.ai/docs/api-reference/events.md) — Submit and query product events for risk evaluation.
- [Sessions API](https://naiza.ai/docs/api-reference/sessions.md) — Session grouping and timeline endpoints.
- [Error Handling](https://naiza.ai/docs/api-reference/errors.md) — Error shapes, status codes, and retry guidance.
- [Rate Limiting](https://naiza.ai/docs/api-reference/rate-limiting.md) — Quota headers and rate-limit behavior.
- [Decisions API](https://naiza.ai/docs/api-reference/decisions.md) — approve / deny / review evaluation and decision payloads (Events API uses ALLOW/REVIEW/BLOCK).

---

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