AML screening report

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.

Didit AML screening report screenshot with sanctions, PEP and adverse media hits

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).

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 page.

Schema

See AML Screening in the Data Models reference 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.
`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.
`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.
`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 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. 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

{
  "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.

{
  "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"
        }
      ]
    }
  ]
}

AML warnings — every warning code AML can emit
AML risk score and AML match score — how the two scores are calculated
Continuous AML monitoring — enabling and consuming monitoring events
Watchlist database — datasets covered
Data models — AML screening — canonical schema
Webhooks — status.updated fires when AML changes the session status; hit review-status changes and monitoring data refreshes fire data.updated

Authentication

Verification

Monitoring

Platform

Overview

Where it appears in API responses

Schema

Per-hit fields

Ongoing monitoring

Status values

Examples

Approved — no hits

In Review — PEP + adverse media hit

​Overview

​Where it appears in API responses

​Schema

​Per-hit fields

​Ongoing monitoring

​Status values

​Examples

​Approved — no hits

​In Review — PEP + adverse media hit

​Related

Overview

Where it appears in API responses

Schema

Per-hit fields

Ongoing monitoring

Status values

Examples

Approved — no hits

In Review — PEP + adverse media hit

Related