# Add AML screening to your app

> Add AML screening with ScreenlyyID: the instance call, the request, the response fields, the decision rule, working Node, Python and Next.js code, and a checklist.

Canonical URL: https://www.screenlyyid.com/docs/guides/aml-screening/

## Summary

AML screening checks a person or an entity (company, organisation or vessel) against sanctions and politically exposed person (PEP) lists and returns the matches with scores and reasons. Use it when you onboard a customer or counterparty, and whenever your obligations require a sanctions check.

## When to use it / when not to

**Use it for:**

- `screening/person`: an individual (name, date of birth, nationality, country, address)
- `screening/entity`: a company, organisation or vessel (name, aliases, registration number, jurisdiction)

**Do not use it for:**

- Document and selfie identity verification is **not** part of this product. It only goes through the Instance API and the hosted capture page: see [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) and [Identity verification (web)](https://www.screenlyyid.com/docs/guides/identity-verification-web/). Do not use the direct identity verification endpoints.
- A match is not a conviction: a human reviews every `potential_match`.

## Before you start

- **API key:** read it from the environment variable `SCREENLYYID_API_KEY` on your **server only**. Use a `test_` key for the sandbox and a `prod_` key for live. Never put it in browser or mobile code. See [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key).
- **Base URL:** `https://api.screenlyyid.com`. HTTPS only.
- **Activation and plan:** The `aml` product must be activated on the account and is listed in `GlobalScreening` in the instance call. Screening is rate limited per account (`429 rate_limited`).
- **Start with the Instance API.** Every flow starts with `POST /api/v1/instance/create`, listing this product's code (`aml`) in `GlobalScreening`. It returns a `CorrelationId` that you send as `x-correlation-id` on the product call, along with `x-api-key`. A product call can be accepted only **once per correlation id**: repeating it with the same id can return `409 duplicate_correlation_id`. Create a new instance for each check (for example one per checkout or per sign-up).

```bash
curl --request POST --url 'https://api.screenlyyid.com/api/v1/instance/create' \
  --header "x-api-key: $SCREENLYYID_API_KEY" --header 'Content-Type: application/json' \
  --data '{"GlobalScreening": ["aml"], "CustomerIntelligence": []}'
# { "CorrelationId": "...", "webEnrolmentUrl": "..." }   (webEnrolmentUrl is only used by the hosted identity verification flow)
```

## Use it on its own or stacked

This product can be called on its own (one instance with just `aml`, as above) or stacked with other products for the same customer: list several product codes in the one instance call and send the same `CorrelationId` on each product's call. See [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/). Example pairing: IDV via the hosted flow + AML screening + eIDV for Tranche 2 client onboarding, or address + phone + AML for a marketplace seller.

Only the direct identity verification endpoints are reference only. Document and selfie identity verification goes through the Instance API and the hosted flow; every other product, including this one, can be called on its own or stacked.

## Implementation steps

1. **Create the instance** in your server code, right before the check. Keep the `CorrelationId` with your own record (the user, the order). Do this on the server.
2. **Call the endpoint** `POST /api/v1/screening/person` with `x-api-key`, `x-correlation-id` and a JSON body (next section). In a typical app this is the onboarding handler, before you activate the customer.
3. **Read the response** and apply the [decision logic](https://www.screenlyyid.com/docs/guides/aml-screening/#decision-logic): the fields marked ★ are the ones to base a decision on.
4. **Act on the result:** accept, ask the customer to correct their input, flag for review, or block. Store the `CorrelationId` and the outcome: it is your audit trail, and the same id shows the check in the dashboard.
5. **Handle failures** (below) so a provider outage never breaks your flow.

## Request and response

### Request
```json
{
  "GivenName": "Jane",
  "FamilyName": "Citizen",
  "DateOfBirth": "1990-01-01",
  "Nationality": "AU",
  "Country": "AU"
}
```

| Field | Type | Meaning | Example |
|---|---|---|---|
| `GivenName / MiddleName / FamilyName` | string | The person's names. | Jane |
| `DateOfBirth` | string | `YYYY`, `YYYY-MM` or `YYYY-MM-DD`. A date of birth sharpens the match. | 1990-01-01 |
| `Nationality` | string | ISO 3166 alpha-2. | AU |
| `Country` | string | Country of the person. | AU |
| `Address` | object | `Line1`, `Locality`, `State`, `PostalCode`, `Country`. |  |
| `Sources` | array | `"dfat"`, `"opensanctions"`. Default: both. | ["dfat"] |
| `Options` | object | `Threshold` (0.5 to 0.99, default 0.8), `Limit` (1 to 20 matches per source, default 5), `Categories` (`"sanction"`, `"pep"`). | { "Threshold": 0.8 } |

The other endpoints in this product: `POST /api/v1/screening/entity`. Each takes its own body (see the request table) and the same headers.

### Response
```json
{
  "correlationId": "d53e3f4d-9a58-4955-8836-a6b8817ea0a3",
  "subjectType": "person",
  "screenedAt": "2026-11-21T05:39:17.7925872+00:00",
  "outcome": "incomplete",
  "sources": [
    {
      "source": "dfat",
      "status": "ok",
      "listVersion": "2026-11-17",
      "listVersionId": 6,
      "dataset": null,
      "algorithm": null,
      "matchCount": 0,
      "error": null
    },
    {
      "source": "opensanctions",
      "status": "ok",
      "listVersion": null,
      "listVersionId": null,
      "dataset": null,
      "algorithm": null,
      "matchCount": 0,
      "error": null
    }
  ],
  "matches": []
}
```

| Field | Type | Meaning | Example |
|---|---|---|---|
| `outcome` | string | ★ `clear`, `potential_match` or `incomplete`. | incomplete |
| `matches[]` | array | ★ Each match: `name`, `score`, `matched`, `categories`, `lists`, `dateOfBirth`, `reasons`. | [] |
| `sources[]` | array | ★ Per source: `source`, `status` (`ok` when the source answered), `matchCount`, `error`. Check that every source is `ok`. |  |
| `correlationId` | string | The instance's id. |  |
| `screenedAt` | string | When the screening ran (UTC). |  |

★ = base your decision on this field.

## Decision logic

1. `outcome` is `potential_match`: stop the onboarding and send the case to a person to review the matches. Do not auto-reject.
2. `outcome` is `clear`: every source answered and nothing matched. Continue.
3. `outcome` is `incomplete`: at least one source did not return `ok` (see `sources[].status`). **Do not treat this as clear.** Retry later or review manually.
4. Keep the full response with the customer record as your audit trail.

```javascript
function amlDecision(res) {
  if (res.outcome === "potential_match") return { action: "review", matches: res.matches };
  if (res.outcome === "incomplete") return { action: "retry_or_review", sources: res.sources };
  return { action: "accept" }; // "clear": every source answered and nothing matched
}
```

## Errors and limits

| Status | When | Body |
|---|---|---|
| `400` | A required field is missing or the body is not valid JSON | A problem-details object: `{"type": "...", "title": "One or more validation errors occurred.", "status": 400, "errors": {"<Field>": ["The <Field> field is required."]}}` |
| `401` | `x-api-key` is missing or malformed, or the product is not activated on the account | Empty body with a `WWW-Authenticate` header |
| `409` | The same `x-correlation-id` was already used for this product | `{"error": "duplicate_correlation_id", "message": "Duplicate correlation id received."}` |
| `500` | The upstream data provider failed | `{"error": "internal_error", "message": "An unexpected error occurred"}` |
| `429` | Screening rate limit reached | `{"error": "rate_limited"}` |
| `502` | Screening is temporarily unavailable | `{"error": "screening_unavailable"}` |

Screening is rate limited per account (`429 rate_limited`; the limit is not published). Retry `502` and `429` with a delay; do not retry `400`. Responses use camelCase property names (unlike most other products).

## Code

Minimal working server-side code. It creates the instance, makes the call with a timeout and throws on a non-`2xx` response with the status and error body attached. The key is read from `SCREENLYYID_API_KEY`.

### JavaScript (Node 18+, fetch)
```javascript
// server only: this reads your API key. Node 18 or later, no dependencies.
const API = "https://api.screenlyyid.com";
const apiKey = process.env.SCREENLYYID_API_KEY; // test_ while building, prod_ in production
if (!apiKey) throw new Error("SCREENLYYID_API_KEY is not set");

// Step 1: one instance per check. It lists this product's code and returns the CorrelationId.
export async function createInstance() {
  const r = await fetch(`${API}/api/v1/instance/create`, {
    method: "POST",
    headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
    body: JSON.stringify({ GlobalScreening: ["aml"], CustomerIntelligence: [] }),
  });
  if (!r.ok) throw new Error(`instance/create failed (HTTP ${r.status})`);
  const { CorrelationId } = await r.json(); // spelled exactly like this
  return CorrelationId;
}

// Step 2: AML screening checks a person or an entity (company, organisation or vessel) against sanctions and politically exposed person (PEP) lists and returns the matches with scores and reasons
export async function screenPerson(person) {
  const correlationId = await createInstance();
  const r = await fetch(`${API}/api/v1/screening/person`, {
    method: "POST",
    headers: { "x-api-key": apiKey, "x-correlation-id": correlationId, "Content-Type": "application/json" },
    body: JSON.stringify(person),
    signal: AbortSignal.timeout(15000),
  });
  if (!r.ok) {
    const error = new Error(`/screening/person failed (HTTP ${r.status})`);
    error.status = r.status;
    error.body = await r.json().catch(() => null);
    throw error;
  }
  return { correlationId, result: await r.json() };
}
```

### Python (requests)
```python
# server only: this reads your API key. Python 3.9 or later, pip install requests
import os
import requests

API = "https://api.screenlyyid.com"
API_KEY = os.environ["SCREENLYYID_API_KEY"]  # test_ while building, prod_ in production


def create_instance():
    """Step 1: one instance per check. It lists this product's code and returns the CorrelationId."""
    r = requests.post(
        f"{API}/api/v1/instance/create",
        headers={"x-api-key": API_KEY},
        json={"GlobalScreening": ["aml"], "CustomerIntelligence": []},
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["CorrelationId"]  # spelled exactly like this


def screen_person(person):
    """Step 2: AML screening checks a person or an entity (company, organisation or vessel) against sanctions and politically exposed person (PEP) lists and returns the matches with scores and reasons"""
    correlation_id = create_instance()
    r = requests.post(
        f"{API}/api/v1/screening/person",
        headers={"x-api-key": API_KEY, "x-correlation-id": correlation_id},
        json=person,
        timeout=15,
    )
    r.raise_for_status()  # a requests.HTTPError carries r.status_code and r.json() for the error body
    return correlation_id, r.json()
```

### Next.js route handler
```javascript
// app/api/screenPerson/route.js (Next.js App Router). The key is read on the server only.
import { screenPerson } from "@/lib/screenlyyid";

export const dynamic = "force-dynamic";

export async function POST(request) {
  const input = await request.json();
  try {
    const { result } = await screenPerson(input);
    return Response.json(result); // send the browser only what it needs, never the API key or the CorrelationId
  } catch (e) {
    // a provider outage or timeout must not break your own flow: decide fail-open or fail-closed here
    return Response.json({ error: "check_unavailable", status: e.status ?? null }, { status: 502 });
  }
}
```

## Test it

`outcome` is `clear` only when every source returns `status` `ok` and nothing matches; if a source is unavailable (for example an error) a no-match screening is `incomplete`. Your code must handle `incomplete`.

| Input | Expected result |
|---|---|
| Vladimir Vladimirovich Putin, born 1952-10-07, nationality RU | `outcome` `potential_match` with a DFAT match, `score` 1, category `sanction`. Use this public example to test the review path. |
| Jane Citizen, country AU | No matches: `outcome` is `clear` when every source answered, and `incomplete` when a source did not. |

## Done when

- [ ] The API key is read only on the server
- [ ] The instance lists `aml` in `GlobalScreening` and the `CorrelationId` is sent as `x-correlation-id`
- [ ] `potential_match` stops the flow and creates a manual review, never an automatic rejection
- [ ] `incomplete` is retried or reviewed, never treated as `clear`
- [ ] The full response is stored as the audit record
- [ ] A test call with the example above returns `potential_match`

## Related

- [Sanctions and AML (API reference)](https://www.screenlyyid.com/docs/api-reference/sanctions-and-aml/)
- [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/)
- [Stacking checks](https://www.screenlyyid.com/docs/guides/stacking-checks/)
