> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# AML screening report
> Parse AML screening responses: hits, sanctions, PEP, adverse media, risk scores, match scores, screened data, and ongoing-monitoring fields.
## Overview
AML screening cross-references the verified subject's identity against global sanctions, PEP, watchlist, and adverse-media datasets. Each hit returns the matched entity, the dataset(s) that produced the match, two scores — `match_score` (identity confidence) and `risk_score` (entity risk) — and a structured breakdown by source (`pep_matches[]`, `sanction_matches[]`, `warning_matches[]`, `adverse_media_matches[]`). The aggregate `score` is the highest `risk_score` among hits that are not marked `False Positive`.
The same shape is returned by AML screening on user (KYC) sessions, business (KYB) sessions, and the standalone AML API.
## Where it appears in API responses
On the session decision endpoint, AML screening is returned as the plural array **`aml_screenings[]`**. Every entry corresponds to one AML execution in the workflow (an AML check that runs twice produces two entries with different `node_id` values).
```text theme={null}
GET /v3/session/{sessionId}/decision/
──▶ { "aml_screenings": [ { node_id, status, total_hits, hits, … }, … ] }
```
Standalone AML and business sessions return the same per-record shape. The fields below mirror the canonical schema on the [Data models](/reference/data-models#aml-screening) page.
## Schema
See [AML Screening in the Data Models reference](/reference/data-models#aml-screening) for the canonical schema. Top-level fields:
| Field | Type | Notes |
| ----------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `Not Finished` \| `Approved` \| `Declined` \| `In Review` | Feature-level status (`FeatureStatusChoices`). Drives workflow rules and the manual-review screen. |
| `total_hits` | integer | Count of entries in `hits[]`. `0` when no matches. |
| `entity_type` | `person` \| `company` | The kind of subject screened. Companies and individuals use different match logic. |
| `score` | float (0-100) \| null | Aggregate AML risk score — the highest `risk_score` among hits not marked `False Positive`. `0` when there are no possible matches; `null` until screening has run. |
| `hits` | `Hit[]` | One entry per matched record, **including** hits auto-classified as `False Positive` (they stay listed but are excluded from the aggregate `score`). See per-hit fields below. |
| `screened_data` | object | The exact values Didit sent to screening: `full_name`, `date_of_birth`, `nationality` (ISO 3166-1 alpha-2), `document_number`. Useful for explaining a hit to a reviewer or auditing what was searched. |
| `is_ongoing_monitoring_enabled` | boolean | `true` once you enable continuous monitoring for the session. |
| `next_ongoing_monitoring_bill_date` | string \| null | `YYYY-MM-DD` of the next annual renewal (`last_aml_bill_date` + 365 days). `null` until monitoring is enabled. |
| `warnings` | `Warning[]` | AML-specific warning tags. See [AML warnings](/core-technology/aml-screening/warnings-aml-screening). |
| `node_id` | string \| null | Identifies the workflow graph node that produced this AML execution on `/v3/` session responses. The standalone AML API response omits it. |
### Per-hit fields
Every entry in `hits[]` has the following fields (subset shown). Match-source arrays — `pep_matches[]`, `sanction_matches[]`, `warning_matches[]`, `adverse_media_matches[]` — are populated only for the dataset(s) the hit belongs to.
| Field | Type | Notes |
| -------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Stable hit identifier. Use it as `hit_id` when updating `review_status` via the AML hit-status endpoint. |
| `caption` | string | The entity's primary name as stored in the dataset. |
| `datasets` | string\[] | E.g. `["PEP"]`, `["PEP Level 1"]`, sanctions list names. |
| `match_score` | number (0-100) | Identity confidence — how likely the hit is the same person. Hits below `aml_match_score_threshold` (default `93`) start as `False Positive`; at or above it they start as `Unreviewed`. See [AML match score](/core-technology/aml-screening/aml-match-score). |
| `risk_score` | number (0-100) | Entity risk — how risky the matched entity is. The highest `risk_score` among non-`False Positive` hits becomes the top-level `score`. See [AML risk score](/core-technology/aml-screening/aml-risk-score). |
| `score` | number (0-1) | **Deprecated** weighted match score. Use `match_score` instead. |
| `match` | boolean \| null | Legacy exact-match flag. Prefer `match_score` + `review_status`. |
| `target` | boolean \| null | Whether the entity is the direct target of the listing. |
| `review_status` | `Unreviewed` \| `Confirmed Match` \| `False Positive` \| `Inconclusive` | Initial value is derived from `match_score` vs `aml_match_score_threshold`. Mutable via the AML hit-status endpoint; updating it fires a `data.updated` webhook but does **not** automatically recompute the feature `status` — use the AML status endpoint or console review for that. |
| `score_breakdown` | object | How `match_score` was calculated: name/DOB/country scores, weights, contributions, and the document-number "golden key" effect (`MATCH` overrides to 100, `NEUTRAL` keeps the base score, `HARD_MISMATCH` penalises). |
| `properties` | object | Raw dataset attributes (names, aliases, birth dates, citizenship, …). Useful for adjudication. |
| `url` | string \| null | Source URL for the matched entity, when available. |
| `rca_name` | string \| null | When the hit is a relative/close associate (RCA), the name of the related person through which it matched. |
| `pep_matches[]` | object\[] | PEP positions, publishers, dates of birth, and education for the hit. |
| `sanction_matches[]` | object\[] | Sanction list name, program, sanctioning authority, listed-on date, and source URLs. |
| `warning_matches[]` | object\[] | Generic watchlist or enforcement-action records. |
| `adverse_media_matches[]` | object\[] | Article-level adverse media: headline, summary, sentiment, source URL, publication date, keywords. |
| `adverse_media_details` | object \| null | Aggregate adverse-media sentiment and keyword counts across the hit. |
| `risk_view` | object | Category-, country-, and crime-weighted risk breakdown for the hit (`risk_level`, `risk_scores`, `weightage`). |
| `linked_entities[]` | object\[] | Related entities the dataset connects to the hit (e.g., family or business associates). |
| `first_seen` / `last_seen` | string \| null | When the dataset first/last observed this entry. |
| `additional_information` | object | Free-form extra data from the dataset provider. |
Hits classified as `False Positive` (because `match_score` fell below the match-score threshold, or because a reviewer marked them) remain in `hits[]` for auditability. They are excluded only from the aggregate `score` calculation.
### Ongoing monitoring
When `is_ongoing_monitoring_enabled` is `true`, Didit re-screens the subject continuously and re-emits the AML report any time a hit is added, removed, or changes. Re-screens that change the AML status fire a `status.updated` webhook; re-screens that only change hit data fire `data.updated`. The monitoring window runs from the `last_aml_bill_date` for 365 days; `next_ongoing_monitoring_bill_date` exposes when the next annual renewal hits. See [Continuous AML monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening) for the full lifecycle.
## Status values
| Value | Meaning |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Not Finished` | AML has not yet executed for this session/node. |
| `Approved` | The aggregate score is at or below the approve threshold (default `80`) — including when there are no hits or every hit is a `False Positive` (score `0`). |
| `In Review` | Aggregate score is above the approve threshold (and at or below the review threshold), or `COULD_NOT_PERFORM_AML_SCREENING` fired. |
| `Declined` | Aggregate score is above the review threshold (default `100`, so auto-decline only happens once you lower it), or the status was set manually. |
The thresholds are configurable per workflow node — see [AML risk score](/core-technology/aml-screening/aml-risk-score). Custom status rules combine with the derived status using `Declined` > `In Review` > `Approved` precedence; reviewers can also override the AML status from the console or the AML status endpoint.
## Examples
### Approved — no hits
```json theme={null}
{
"aml_screenings": [
{
"node_id": "aml-1",
"status": "Approved",
"total_hits": 0,
"entity_type": "person",
"score": 0,
"hits": [],
"screened_data": {
"full_name": "Jane Doe",
"nationality": "US",
"date_of_birth": "1990-06-12",
"document_number": "P9876543"
},
"is_ongoing_monitoring_enabled": false,
"next_ongoing_monitoring_bill_date": null,
"warnings": []
}
]
}
```
### In Review — PEP + adverse media hit
All names, URLs, and articles below are fictional.
```json theme={null}
{
"aml_screenings": [
{
"node_id": "aml-1",
"status": "In Review",
"total_hits": 1,
"entity_type": "person",
"score": 85,
"hits": [
{
"id": "cPtTGRKkyddAcAC4xgsLCm",
"caption": "John Q. Exampleton",
"datasets": ["PEP"],
"match_score": 96,
"risk_score": 85,
"score": 0.97,
"match": false,
"target": null,
"review_status": "Unreviewed",
"properties": {
"name": ["John Q. Exampleton"],
"alias": ["Johnny Example"],
"birthDate": ["1974"],
"birthPlace": ["Springfield"]
},
"score_breakdown": {
"name_score": 95,
"name_weight": 60,
"name_weight_normalized": 70.59,
"name_contribution": 67.06,
"dob_score": 100,
"dob_weight": 25,
"dob_weight_normalized": 29.41,
"dob_contribution": 29.41,
"country_score": 0,
"country_weight": 15,
"country_weight_normalized": 0,
"country_contribution": 0,
"document_number_match_type": "NEUTRAL",
"document_number_effect": "No document number provided for screening",
"total_score": 96
},
"pep_matches": [
{
"list_name": "Example PEP Registry",
"publisher": "Example Registry",
"matched_name": "John Q. Exampleton",
"pep_position": "Regional council member",
"date_of_birth": "1974-01-01",
"place_of_birth": "Springfield",
"source_url": "https://example.org/registry/entities/Q0000001"
}
],
"sanction_matches": [],
"warning_matches": [],
"adverse_media_matches": [
{
"country": "freedonia",
"headline": "Court opens inquiry into council hiring irregularities",
"summary": "John Q. Exampleton is named in a legal investigation regarding irregularities in public hiring.",
"sentiment": "moderately negative",
"sentiment_score": -2,
"source_url": "https://example-news.org/articles/12345",
"publication_date": "2025-06-09T10:19:10",
"adverse_keywords": ["fraud", "irregularities"]
}
],
"adverse_media_details": {
"sentiment": "Moderately Negative",
"sentiment_score": -2,
"entity_type": "person",
"adverse_keywords": { "fraud": 3, "corruption": 2 }
},
"risk_view": {
"categories": { "score": 100.0, "weightage": 50, "risk_level": "High", "risk_scores": { "PEP": 100.0 } },
"countries": { "score": 0.0, "weightage": 30, "risk_level": "Low", "risk_scores": {} },
"crimes": { "score": 0.0, "weightage": 20, "risk_level": "Low", "risk_scores": {} },
"custom_list": {}
},
"linked_entities": [
{ "name": ["Mary Exampleton"], "relation": [], "details": [], "active": [], "status": [] }
],
"first_seen": "2025-01-18T00:00:00",
"last_seen": "2025-06-13T00:00:00"
}
],
"screened_data": {
"full_name": "John Q. Exampleton",
"nationality": "US",
"date_of_birth": "1974-01-01",
"document_number": null
},
"is_ongoing_monitoring_enabled": true,
"next_ongoing_monitoring_bill_date": "2027-05-17",
"warnings": [
{
"feature": "AML",
"risk": "POSSIBLE_MATCH_FOUND",
"additional_data": null,
"log_type": "warning",
"short_description": "Possible match found in AML screening",
"long_description": "The Anti-Money Laundering (AML) screening process identified potential matches with watchlists or high-risk databases, requiring further review.",
"node_id": "aml-1"
}
]
}
]
}
```
## Related
* [AML warnings](/core-technology/aml-screening/warnings-aml-screening) — every warning code AML can emit
* [AML risk score](/core-technology/aml-screening/aml-risk-score) and [AML match score](/core-technology/aml-screening/aml-match-score) — how the two scores are calculated
* [Continuous AML monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening) — enabling and consuming monitoring events
* [Watchlist database](/core-technology/aml-screening/watchlist-database-aml-screening) — datasets covered
* [Data models — AML screening](/reference/data-models#aml-screening) — canonical schema
* [Webhooks](/integration/webhooks) — `status.updated` fires when AML changes the session status; hit review-status changes and monitoring data refreshes fire `data.updated`