ScreenlyyIDDocs
Docs › Guides

Add AML screening to your app

View as Markdown

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_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.
  • 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).
Shell
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#

  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: 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"
}
FieldTypeMeaningExample
GivenName / MiddleName / FamilyNamestringThe person's names.Jane
DateOfBirthstringYYYY, YYYY-MM or YYYY-MM-DD. A date of birth sharpens the match.1990-01-01
NationalitystringISO 3166 alpha-2.AU
CountrystringCountry of the person.AU
AddressobjectLine1, Locality, State, PostalCode, Country.
Sourcesarray"dfat", "opensanctions". Default: both.["dfat"]
OptionsobjectThreshold (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": []
}
FieldTypeMeaningExample
outcomestring★ 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.
correlationIdstringThe instance's id.
screenedAtstringWhen 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#

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

InputExpected result
Vladimir Vladimirovich Putin, born 1952-10-07, nationality RUoutcome potential_match with a DFAT match, score 1, category sanction. Use this public example to test the review path.
Jane Citizen, country AUNo 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