AML screening

Choosing the right tool

The API gives you three complementary ways to keep bad actors out, from a one-line check to fully automatic monitoring:

1 · Run a list check

POST /v1/aml-checks verifies a name against sanctions, PEP and watchlist data in a single call. The subject does not need to be a VirtuaBroker customer — this is verification-as-a-service for your own onboarding, your client portfolio, or any counterparty you need to vet.

curl https://api.virtuabroker.com/v1/aml-checks \
  -H "Authorization: Bearer $VB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "012345678A",
    "name": "El payaso Miliki",
    "reference": "client-check-456"
  }'

const res = await fetch("https://api.virtuabroker.com/v1/aml-checks", {
  method: "POST",
  headers: { Authorization: `Bearer ${access_token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    id: "012345678A",
    name: "El payaso Miliki",
    reference: "client-check-456",
  }),
});
const check = await res.json();

check = requests.post("https://api.virtuabroker.com/v1/aml-checks",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "id": "012345678A",
        "name": "El payaso Miliki",
        "reference": "client-check-456",
    },
).json()

A clean subject comes back with match: false and an empty results array:

{
  "checkId": "3JyVix1grJsu1z64h047",
  "reference": "client-check-456",
  "status": "COMPLETED",
  "match": false,
  "matchCount": 0,
  "checkedAt": "2026-07-20T09:00:00.000Z",
  "results": []
}

A potential match returns the list entries, each with a similarity score and the reasons the entry is listed:

{
  "checkId": "8kQpWv2xTzRb5cJd9eYf",
  "status": "COMPLETED",
  "match": true,
  "matchCount": 1,
  "checkedAt": "2026-07-20T09:01:00.000Z",
  "results": [
    {
      "matchId": "Q6070218",
      "name": "Pedro Sánchez",
      "type": "PERSON",
      "score": 1,
      "flags": ["PEP"],
      "title": "Prime Minister of Spain",
      "countries": ["ES"],
      "dateOfBirth": "1972-02-29"
    }
  ]
}

If the check cannot run, the response is a 503 with match: null, status: "FAILED" and a coded errors array (CHECK_NOT_COMPLETED). The failed check is stored too — retrieving it later returns the same honest FAILED view. Retry with a new check; never treat it as a pass.

2 · Retrieve a stored check

GET /v1/aml-checks/{checkId} returns a previously run check. Checks are visible only to the workspace that created them; repeat checks of the same subject each produce their own record, so your audit trail shows every verification with its timestamp.

curl https://api.virtuabroker.com/v1/aml-checks/3JyVix1grJsu1z64h047 \
  -H "Authorization: Bearer $VB_TOKEN"

3 · Run an identity-rich screening

When you hold more than a name, POST /v1/aml-screenings screens with the full identity — date of birth, nationality, tax identifiers — for a higher-precision outcome and a review lifecycle. Richer identity information produces higher-quality screening.

curl https://api.virtuabroker.com/v1/aml-screenings \
  -H "Authorization: Bearer $VB_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboarding-7f3a2b" \
  -d '{
    "entity": {
      "entityType": "INDIVIDUAL",
      "firstName": "John",
      "lastName": "Smith",
      "dateOfBirth": "1985-03-14",
      "nationality": "GB",
      "taxIdentificationNumber": "X1234567L",
      "taxIdentificationType": "NIE",
      "taxIdentificationCountry": "ES"
    },
    "reason": "ONBOARDING",
    "reference": "client-check-456"
  }'

Companies use entityType: "COMPANY" with companyName, companyRegistrationNumber and countryOfResidence. At least one name (or an identifier that resolves to a known account) is required.

{
  "screeningId": "5mRtYu8wQaSd2fGh4jKl",
  "reference": "client-check-456",
  "status": "COMPLETED",
  "result": "CLEAR",
  "match": false,
  "potentialMatchCount": 0,
  "reviewRequired": false,
  "screenedAt": "2026-07-20T09:02:00.000Z"
}

Screenings summarise the outcome — result, match, counts. Raw match details are retained for compliance review and are not returned on this resource (the list check above is the endpoint that returns match details). Retrieve a screening later with GET /v1/aml-screenings/{screeningId}.

4 · Continuous screening — automatic

List data changes daily: people become PEPs, sanctions are added, watchlists grow. Continuous screening closes that gap with zero integration work:

Error handling & best practices

Errors

Best practices

• Branch on match === false. match is tri-state — testing "not true" turns an outage into a false pass.
• Store the checkId/screeningId. They are your audit evidence; reference ties them back to your own systems.
• Retries are safe. A repeat POST /v1/aml-checks appends a new history record; a repeat screening with the same Idempotency-Key replays the original.
• A score is a lead, not a verdict. score measures name similarity; a potential match needs human review before you act on it — especially common names.
• Re-check long-lived counterparties. For subjects outside the platform's continuous screening, schedule periodic re-checks — list data moves.

Quick reference