Skip to main content

​
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:
FieldTypeNotes
statusNot Finished | Approved | Declined | In ReviewFeature-level status (FeatureStatusChoices). Drives workflow rules and the manual-review screen.
total_hitsintegerCount of entries in hits[]. 0 when no matches.
entity_typeperson | companyThe kind of subject screened. Companies and individuals use different match logic.
scorefloat (0-100) | nullAggregate 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.
hitsHit[]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_dataobjectThe 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_enabledbooleantrue once you enable continuous monitoring for the session.
next_ongoing_monitoring_bill_datestring | nullYYYY-MM-DD of the next annual renewal (last_aml_bill_date + 365 days). null until monitoring is enabled.
warningsWarning[]AML-specific warning tags. See AML warnings.
node_idstring | nullIdentifies 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.
FieldTypeNotes
idstringStable hit identifier. Use it as hit_id when updating review_status via the AML hit-status endpoint.
captionstringThe entity’s primary name as stored in the dataset.
datasetsstring[]E.g. ["PEP"], ["PEP Level 1"], sanctions list names.
match_scorenumber (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_scorenumber (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.
scorenumber (0-1)Deprecated weighted match score. Use match_score instead.
matchboolean | nullLegacy exact-match flag. Prefer match_score + review_status.
targetboolean | nullWhether the entity is the direct target of the listing.
review_statusUnreviewed | Confirmed Match | False Positive | InconclusiveInitial 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_breakdownobjectHow 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).
propertiesobjectRaw dataset attributes (names, aliases, birth dates, citizenship, …). Useful for adjudication.
urlstring | nullSource URL for the matched entity, when available.
rca_namestring | nullWhen 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_detailsobject | nullAggregate adverse-media sentiment and keyword counts across the hit.
risk_viewobjectCategory-, 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_seenstring | nullWhen the dataset first/last observed this entry.
additional_informationobjectFree-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

ValueMeaning
Not FinishedAML has not yet executed for this session/node.
ApprovedThe 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 ReviewAggregate score is above the approve threshold (and at or below the review threshold), or COULD_NOT_PERFORM_AML_SCREENING fired.
DeclinedAggregate 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"
        }
      ]
    }
  ]
}