Add AML screening to your app
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) and 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_KEYon your server only. Use atest_key for the sandbox and aprod_key for live. Never put it in browser or mobile code. See Get a test key. - Base URL:
https://api.screenlyyid.com. HTTPS only. - Activation and plan: The
amlproduct must be activated on the account and is listed inGlobalScreeningin 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) inGlobalScreening. It returns aCorrelationIdthat you send asx-correlation-idon the product call, along withx-api-key. A product call can be accepted only once per correlation id: repeating it with the same id can return409 duplicate_correlation_id. Create a new instance for each check (for example one per checkout or per sign-up).
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. 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#
- Create the instance in your server code, right before the check. Keep the
CorrelationIdwith your own record (the user, the order). Do this on the server. - Call the endpoint
POST /api/v1/screening/personwithx-api-key,x-correlation-idand a JSON body (next section). In a typical app this is the onboarding handler, before you activate the customer. - Read the response and apply the decision logic: the fields marked ★ are the ones to base a decision on.
- Act on the result: accept, ask the customer to correct their input, flag for review, or block. Store the
CorrelationIdand the outcome: it is your audit trail, and the same id shows the check in the dashboard. - Handle failures (below) so a provider outage never breaks your flow.
Request and response#
Request#
{
"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#
{
"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#
outcomeispotential_match: stop the onboarding and send the case to a person to review the matches. Do not auto-reject.outcomeisclear: every source answered and nothing matched. Continue.outcomeisincomplete: at least one source did not returnok(seesources[].status). Do not treat this as clear. Retry later or review manually.- Keep the full response with the customer record as your audit trail.
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)#
// 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)#
# 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#
// 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
amlinGlobalScreeningand theCorrelationIdis sent asx-correlation-id - [ ]
potential_matchstops the flow and creates a manual review, never an automatic rejection - [ ]
incompleteis retried or reviewed, never treated asclear - [ ] The full response is stored as the audit record
- [ ] A test call with the example above returns
potential_match