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.

Three scores, not one verdict

The status is a verdict; the numbers it was derived from are in the same payload. Read them when you build your own risk tiering (for example combining AML risk with questionnaire answers such as source of wealth or PEP self-declaration) instead of branching only on Approved / In Review / Declined:

Score	Where	Scale	Answers
`hits[].match_score`	per hit	0-100	Is this hit the same person as the one screened? Decides the hit’s initial `review_status`.
`hits[].risk_score`	per hit	0-100	How risky is the matched entity? Driven by the hit’s categories (sanction, PEP, crime, …).
`score`	per screening	0-100	The highest `risk_score` among hits not marked `False Positive`. This is what the approve / review thresholds are compared with to produce `status`.

All three are present in every place the AML report is delivered: GET /v3/session/{sessionId}/decision/, the decision object of status.updated and data.updated webhooks on every webhook version (V3 aml_screenings[], and the legacy V2 / V1 singular aml), and the standalone AML API. A consumer that sees only a flagged / clear label is reading status (or a hit’s review_status) and skipping the scores next to it. The console shows the same numbers: the AML section header carries the aggregate Risk score, and every row of the matches table carries Match score and Risk score with a breakdown on hover.

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 billing renewal (`last_aml_bill_date` + 365 days). `null` until monitoring is enabled. This is not a screening date — see `last_ongoing_screening_at` below.
`last_ongoing_screening_at`	string (ISO 8601) \| null	When ongoing monitoring last completed a re-screening of this record, whether or not the result changed. `null` when the record has never been re-screened since this field shipped — it is never back-filled from the enablement or billing date.
`last_ongoing_screening_datasets_updated_at`	string (ISO 8601) \| null	The most recent AML dataset update date the provider reported at the time of that screening. `null` when the provider reported no dataset dates; it is never estimated.
`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. Those signals are all change-driven, so a subject re-screened for months with no new hits produces none of them. last_ongoing_screening_at is the one field that moves on every completed run, and the screening-history endpoint lists each run individually — including the ones that changed nothing. See Continuous AML monitoring for the full lifecycle.

Three dates on this report mean three different things. next_ongoing_monitoring_bill_date is when you are billed next. last_ongoing_screening_at is when the subject was last actually screened. last_ongoing_screening_datasets_updated_at is when the lists behind that screening were last refreshed by the provider. Only the second one evidences that the control ran.

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,
      "last_ongoing_screening_at": null,
      "last_ongoing_screening_datasets_updated_at": null,
      "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

Three scores, not one verdict

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

​Three scores, not one verdict

​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

Three scores, not one verdict

Schema

Per-hit fields

Ongoing monitoring

Status values

Examples

Approved — no hits

In Review — PEP + adverse media hit

Related