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": "..." } ]
}

Field	Type	Notes
`status`	enum	Run-level status. `COMPLETED`, `FAILED`, or `PENDING`.
`num_hits`	int	Total number of matched entities.
`entity_hits`	array	One per matched entity. See below.
`result`	enum	Auto-derived: `APPROVED` if zero hits, `REVIEW` if ≥1 hit, `DECLINED` on input-validation failures, `UNKNOWN` otherwise.
`section_id`	uuid	Stable identifier for this AML section — use to correlate resolution status updates.
`warnings`	array	Non-fatal warnings produced during the run. See below.
`aml_hit_summary`	object	Hit counts keyed by hit type. PEP sub-classes roll up to `PEP`; adverse-media sub-types roll up to `ADVERSE_MEDIA`.
`search_criteria`	object	The query used. `fuzziness_score` is `0.0`–`1.0`. `birth_year` is present for person searches.
`status_reasons`	array	Present only on failure.

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 */ ]
}

Field	Type	Notes
`entity_type`	enum	`PERSON` / `COMPANY` / `ORGANISATION` / `UNKNOWN`. For user AML checks this is typically `PERSON`.
`name`	string	Matched name on the source side.
`name_match_score`	float	Score `0`–`100` of how closely the source name matches the input.
`date_of_birth`	string	`YYYY-MM-DD` if present on the source.
`date_of_birth_match_score`	float	Score `0`–`100` of DOB match.
`also_known_as`	array<string>	Known aliases.
`associates`	array	Each: `{ name, association }`.
`aml_hits`	array	One per source the entity appears on (a single sanctions list, a single adverse-media cluster, etc).
`id`	uuid	Stable identifier for this hit — use to attach resolution decisions.
`resolution_status`	enum	`UNRESOLVED` / `RESOLVED` / `WHITELISTED`. Reflects the latest status.
`is_deleted`	bool	`true` if the source removed this hit (relevant for ongoing monitoring).
`aml_agent_analysis`	object	Present when AiPrise's AML AI Agent has run. Contains relevance score, severity assessment, recommendation, reasoning, citations.
`history`	array	Timeline of monitoring updates for this entity. Present when continuous monitoring is enabled.

`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",
        "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": "..." }
    ]
}

Field	Type	Notes
`hit_type`	enum	See enums below for the full list.
`source_details`	object	Metadata about the list/source.
`source_details.listing_started` / `listing_ended`	string	Unix timestamp in seconds, as a string.
`source_details.country_codes`	array<string>	May contain country codes or full country names depending on the source.
`source_details.aml_types`	array<string>	Raw source-side hit-type tags.
`fields`	array	Structured fields from the source. Each: `{ name, value, type? }`. `value` can be a string, list, or dict.
`media`	array	Populated only when `hit_type` is `ADVERSE_MEDIA`. Each: `{ title, url, date, snippet }`. `date` is a Unix-seconds string.

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 sub-classes (roll up to ADVERSE_MEDIA in aml_hit_summary):

ADVERSE_MEDIA_PROPERTY
ADVERSE_MEDIA_FINANCIAL_AML_CFT
ADVERSE_MEDIA_FRAUD_LINKED
ADVERSE_MEDIA_NARCOTICS_AML_CFT
ADVERSE_MEDIA_VIOLENCE_AML_CFT
ADVERSE_MEDIA_TERRORISM
ADVERSE_MEDIA_CYBERCRIME
ADVERSE_MEDIA_GENERAL_AML_CFT
ADVERSE_MEDIA_REGULATORY
ADVERSE_MEDIA_FINANCIAL_DIFFICULTY
ADVERSE_MEDIA_VIOLENCE_NON_AML_CFT
ADVERSE_MEDIA_OTHER_FINANCIAL
ADVERSE_MEDIA_OTHER_SERIOUS
ADVERSE_MEDIA_OTHER_MINOR

Individual aml_hits[*].hit_type values may be a sub-class (e.g. ADVERSE_MEDIA_FRAUD_LINKED); aml_hit_summary keys are always rolled up to the top-level type.

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.