User AML Check

This API can be used to verify whether a user is listed in over 10,000 watchlists from across the world such as:

• OFAC, SDN, Interpol, FBI etc.
• Politically Exposed Persons(PEP) from around the world.
• Criminal lists, Most Wanted lists from different countries.

This API also returns Adverse Media(Bad press) matches.

Request

{
    "template_id" : "{{YOUR_TEMPLATE_ID}}",
    "user_data": {
        "first_name": "REQUIRED",
        "middle_name": "OPTIONAL",
        "last_name": "REQUIRED",
        "date_of_birth": "YYYY-MM-DD (OPTIONAL)",
        "identity": {
            "identity_country_code": "XX (OPTIONAL)"
        }
    }
}

Response

The AML result is returned inside the aml_info block on the verification response. Fields with null values are omitted from the response.

Top-level

{
    "status": "COMPLETED | FAILED | PENDING",
    "result": "APPROVED | DECLINED | REVIEW | UNKNOWN",
    "aml_info": { ... }
}

aml_info

{
    "status": "COMPLETED | FAILED | PENDING",
    "num_hits": 0,
    "entity_hits": [ /* see entity_hits */ ],
    "result": "APPROVED | DECLINED | REVIEW | UNKNOWN",
    "section_id": "<uuid>",
    "warnings": [ /* see warnings */ ],
    "aml_hit_summary": {
        "SANCTION": 0,
        "PEP": 1,
        "ADVERSE_MEDIA": 2,
        "WARNING": 0
    },
    "search_criteria": {
        "search_term": "John Doe",
        "fuzziness_score": 0.6,
        "exact_match": false,
        "birth_year": 1980
    },
    "status_reasons": [ { "code": "...", "message": "..." } ]
}

Failure shapes

When the run fails or required input is missing, aml_info collapses to one of:

// Missing required input (e.g. no last name)
{
    "status": "COMPLETED",
    "result": "DECLINED",
    "warnings": [{ "code": "API_DATA_REQUIREMENTS_NOT_MET", "message": "Missing last name to run check." }]
}

// Provider call failed
{
    "status": "FAILED",
    "status_reasons": [{ "code": "THIRD_PARTY_API_FAILED", "message": "..." }]
}

// Provider response unparseable
{
    "status": "FAILED",
    "status_reasons": [{ "code": "THIRD_PARTY_RESPONSE_ERROR", "message": "..." }]
}

entity_hits[*]

One object per matched person.

{
    "entity_type": "PERSON | COMPANY | ORGANISATION | UNKNOWN",
    "name": "Matched name",
    "name_match_score": 87.5,
    "date_of_birth": "1980-05-12",
    "date_of_birth_match_score": 100.0,
    "also_known_as": ["Johnny Doe", "J. Doe"],
    "associates": [
        { "name": "Jane Doe", "association": "spouse" }
    ],
    "aml_hits": [ /* see aml_hits */ ],
    "id": "<uuid>",
    "resolution_status": "UNRESOLVED | RESOLVED | WHITELISTED",
    "is_deleted": false,
    "aml_agent_analysis": { /* AI agent output: relevance, severity, recommendation, citations */ },
    "history": [ /* monitoring timeline */ ]
}

aml_hits[*]

One entry per source the entity appears on. An entity on N lists produces N entries.

{
    "hit_type": "SANCTION",
    "source_details": {
        "name": "OFAC SDN List",
        "source_id": "ofac-sdn-list",
        "url": "https://...",
        "listing_started": "1577836800",
        "listing_ended": null,
        "country_codes": ["US"],
        "aml_types": ["sanction"]
    },
    "fields": [
        { "name": "Date of Birth", "value": "1980-05-12", "type": "date_of_birth" },
        { "name": "Country", "value": ["US", "GB"], "type": "country_codes" }
    ],
    "media": [
        { "title": "...", "url": "https://...", "date": "1700000000", "snippet": "..." }
    ]
}

source_details.aml_types

aml_types carries the granular, source-side classification for a hit as lowercase, hyphenated tags. This is distinct from the hit's hit_type, which is the uppercase roll-up category (SANCTION, PEP, ADVERSE_MEDIA, WARNING, …). For example, an adverse-media hit always has hit_type ADVERSE_MEDIA, while its specific sub-category appears in aml_types as e.g. adverse-media-v2-fraud-linked.

These are provider-taxonomy tags, not a customer-defined enum. Any finer-grained categorization on your side must map into these returned values — we do not return more granular offense-level codes.

The full set of values:

• sanction
• warning
• pep, pep-class-1, pep-class-2, pep-class-3, pep-class-4
• fitness-probity
• adverse-media

Adverse-media sub-categories:

• adverse-media-v2-financial-aml-cft
• adverse-media-v2-fraud-linked
• adverse-media-v2-narcotics-aml-cft
• adverse-media-v2-terrorism
• adverse-media-v2-violence-aml-cft
• adverse-media-v2-violence-non-aml-cft
• adverse-media-v2-cybercrime
• adverse-media-v2-property
• adverse-media-v2-regulatory
• adverse-media-v2-financial-difficulty
• adverse-media-v2-other-financial
• adverse-media-v2-other-serious
• adverse-media-v2-other-minor
• adverse-media-v2-general-aml-cft

Enforcement / WARNING hits

Enforcement, regulator, and law-enforcement list matches are surfaced with hit_type WARNING. For these hits, source_details.aml_types is always ["warning"] — there are no sub-types. The specific list that triggered the hit is identified by:

• source_details.source_id — machine-readable list identifier.
• source_details.name — human-readable list name.

These list identifiers are not a fixed enum. They come from our screening provider, span hundreds of country-specific regulator and law-enforcement lists, and grow over time. Integrators should key their rules on hit_type == WARNING and treat source_id / name as free-form metadata rather than matching against a hardcoded set.

Representative (non-exhaustive) examples:

Enums

status — run status: COMPLETED, FAILED, PENDING.

result — overall verdict: APPROVED (no hits), REVIEW (≥1 hit), DECLINED (input requirements not met), UNKNOWN.

resolution_status — UNRESOLVED (default), RESOLVED, WHITELISTED.

entity_type — PERSON, COMPANY, ORGANISATION, UNKNOWN.

hit_type — top-level (roll-up) types, used as keys in aml_hit_summary:

• SANCTION
• PEP
• ADVERSE_MEDIA
• WARNING
• FITNESS_PROBITY
• CRIMINAL_RECORD
• LEGAL_BACKGROUND
• UNKNOWN

PEP sub-classes (roll up to PEP in aml_hit_summary):

• PEP_CLASS_1, PEP_CLASS_2, PEP_CLASS_3, PEP_CLASS_4

Adverse-media hits are not sub-classed in hit_type: every adverse-media hit carries hit_type ADVERSE_MEDIA. The granular adverse-media classification is carried in source_details.aml_types as a lowercase, hyphenated tag (e.g. adverse-media-v2-fraud-linked) — see source_details.aml_types for the full set.

aml_hit_summary keys are always the top-level roll-up type. An individual aml_hits[*].hit_type for a PEP match may be a PEP sub-class (PEP_CLASS_1–PEP_CLASS_4), which rolls up to PEP in the summary.

fields[*].type — date_of_birth, place_of_birth, date_of_death, country_codes, country_names, url.

Warnings & status reasons

warnings[*]:

{
    "code": "API_DATA_REQUIREMENTS_NOT_MET",
    "message": "Human-readable description",
    "resolution_status": "UNRESOLVED | RESOLVED | WHITELISTED",
    "warning_id": "<uuid>"
}

• code identifies the warning class.
• message is a human-readable description.
• warning_id is stable — use to track resolution over time.

status_reasons[*]:

{ "code": "THIRD_PARTY_API_FAILED", "message": "..." }

Common AML status reasons:

• THIRD_PARTY_API_FAILED — upstream provider call errored.
• THIRD_PARTY_RESPONSE_ERROR — upstream provider returned an unparseable response.