Report di screening AML: hit, punteggi e JSON

Panoramica

Lo screening AML confronta l’identità del soggetto verificato con dataset globali di sanzioni, PEP, watchlist e notizie negative. Ogni riscontro restituisce l’entità corrispondente, i dataset che hanno generato la corrispondenza, due punteggi — match_score (affidabilità dell’identità) e risk_score (rischio dell’entità) — e una suddivisione strutturata per fonte (pep_matches[], sanction_matches[], warning_matches[], adverse_media_matches[]). Il valore aggregato score è il risk_score più alto tra i riscontri non contrassegnati come False Positive. La stessa struttura viene restituita dallo screening AML nelle sessioni utente (KYC), nelle sessioni aziendali (KYB) e nell’API AML autonoma.

Screenshot del report dello screening AML di Didit con riscontri di sanzioni, PEP e notizie negative

Dove compare nelle risposte dell’API

Sull’endpoint della decisione della sessione, lo screening AML viene restituito come array plurale aml_screenings[]. Ogni voce corrisponde a un’esecuzione AML nel workflow (un controllo AML eseguito due volte produce due voci con valori node_id differenti).

GET /v3/session/{sessionId}/decision/
  ──▶ { "aml_screenings": [ { node_id, status, total_hits, hits, … }, … ] }

L’API AML autonoma e le sessioni aziendali restituiscono la stessa struttura per ogni record. I campi sottostanti rispecchiano lo schema canonico nella pagina Modelli di dati.

Tre punteggi, non un solo verdetto

Lo status è un verdetto; i numeri da cui è stato ricavato si trovano nello stesso payload. Consultali quando crei la tua suddivisione per livelli di rischio (ad esempio combinando il rischio AML con le risposte ai questionari come l’origine del patrimonio o l’autodichiarazione PEP) invece di basarti solo su Approved / In Review / Declined:

Punteggio	Dove	Scala	Risponde a
`hits[].match_score`	per riscontro	0-100	Questo riscontro corrisponde alla stessa persona sottoposta a screening? Determina il `review_status` iniziale del riscontro.
`hits[].risk_score`	per riscontro	0-100	Quanto è rischiosa l’entità corrispondente? È determinato dalle categorie del riscontro (sanzione, PEP, reato, …).
`score`	per screening	0-100	Il `risk_score` più alto tra i riscontri non contrassegnati come `False Positive`. È il valore confrontato con le soglie di approvazione / revisione per generare lo `status`.

Tutti e tre sono presenti in ogni contesto in cui viene fornito il report AML: GET /v3/session/{sessionId}/decision/, l’oggetto decision dei webhook status.updated e data.updated su ogni versione dei webhook (V3 aml_screenings[], e il formato legacy V2 / V1 al singolare aml), nonché l’API AML autonoma. Chi legge solo un’etichetta con segnalazioni o senza segnalazioni sta leggendo status (o il review_status di un riscontro) ignorando i punteggi accanto. La console mostra gli stessi numeri: l’intestazione della sezione AML riporta il Punteggio di rischio aggregato, e ogni riga della tabella delle corrispondenze riporta Punteggio corrispondenza e Punteggio di rischio con un dettaglio al passaggio del mouse.

Schema

Consulta Screening AML nel riferimento ai modelli di dati per lo schema canonico. Campi di primo livello:

Campo	Tipo	Note
`status`	`Not Finished` \| `Approved` \| `Declined` \| `In Review`	Stato a livello di funzionalità (`FeatureStatusChoices`). Determina le regole del workflow e la schermata di revisione manuale.
`total_hits`	integer	Numero di voci in `hits[]`. `0` in assenza di corrispondenze.
`entity_type`	`person` \| `company`	Il tipo di soggetto sottoposto a screening. Le aziende e le persone fisiche utilizzano una logica di corrispondenza diversa.
`score`	float (0-100) \| null	Punteggio di rischio AML aggregato — il `risk_score` più elevato tra i riscontri non contrassegnati come `False Positive`. `0` quando non ci sono corrispondenze possibili; `null` fino all’esecuzione dello screening.
`hits`	`Hit[]`	Una voce per ciascun record corrispondente, inclusi i riscontri classificati automaticamente come `False Positive` (rimangono elencati ma sono esclusi dal `score` aggregato). Consulta i campi per singolo riscontro di seguito.
`screened_data`	object	I valori esatti inviati da Didit allo screening: `full_name`, `date_of_birth`, `nationality` (ISO 3166-1 alpha-2), `document_number`. Utile per spiegare un riscontro a un revisore o per verificare cosa è stato cercato.
`is_ongoing_monitoring_enabled`	boolean	`true` una volta abilitato il monitoraggio continuo per la sessione.
`next_ongoing_monitoring_bill_date`	string \| null	`YYYY-MM-DD` del prossimo rinnovo annuale per la fatturazione (`last_aml_bill_date` + 365 giorni). `null` finché il monitoraggio non viene abilitato. Questa non è una data di screening — vedi `last_ongoing_screening_at` di seguito.
`last_ongoing_screening_at`	string (ISO 8601) \| null	Quando il monitoraggio continuo ha completato l’ultima nuova verifica di questo record, a prescindere dal fatto che il risultato sia cambiato o meno. `null` se il record non è mai stato sottoposto a un nuovo screening da quando questo campo è stato introdotto — non viene mai retrodatato a partire dalla data di abilitazione o di fatturazione.
`last_ongoing_screening_datasets_updated_at`	string (ISO 8601) \| null	La data di aggiornamento del dataset AML più recente segnalata dal provider al momento di tale screening. `null` quando il provider non ha comunicato alcuna data per i dataset; non viene mai stimata.
`warnings`	`Warning[]`	Tag di avviso specifici per AML. Consulta gli avvisi AML.
`node_id`	string \| null	Identifica il nodo del grafo del workflow che ha prodotto questa esecuzione AML nelle risposte della sessione su `/v3/`. La risposta dell’API AML autonoma lo omette.

Campi per singolo riscontro

Ciascuna voce in hits[] presenta i seguenti campi (ne viene mostrato un sottoinsieme). Gli array delle origini di corrispondenza — pep_matches[], sanction_matches[], warning_matches[], adverse_media_matches[] — vengono compilati solo per i dataset a cui appartiene il riscontro.

Campo	Tipo	Note
`id`	string	Identificativo stabile del riscontro: `hit_` seguito da 24 caratteri esadecimali. La stessa entità corrispondente mantiene lo stesso `id` quando il soggetto viene sottoposto nuovamente a screening. Usalo come `hit_id` quando aggiorni `review_status` tramite l’endpoint per lo stato dei riscontri AML.
`caption`	string	Il nome principale dell’entità memorizzato nel dataset.
`datasets`	string[]	Categorie di rischio in cui è elencata l’entità: `PEP` (con il relativo livello, da `PEP Level 1` a `PEP Level 4`), `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`, `SIP`, `SIE` o `Insolvency`, e `Other Lists` quando la fonte dell’entità non specifica nessuna di queste.
`match_score`	number (0-100)	Affidabilità dell’identità — quanto è probabile che il riscontro corrisponda alla stessa persona. I riscontri al di sotto di `aml_match_score_threshold` (valore predefinito `93`) partono come `False Positive`; pari o superiori partono come `Unreviewed`. Consulta Punteggio di corrispondenza AML.
`risk_score`	number (0-100)	Rischio dell’entità — quanto è rischiosa l’entità corrispondente. Il `risk_score` più elevato tra i riscontri che non sono `False Positive` diventa il valore `score` di primo livello. Consulta Punteggio di rischio AML.
`score`	number (0-1)	Punteggio di corrispondenza ponderato deprecato. Usa invece `match_score`.
`match`	boolean \| null	Flag legacy di corrispondenza esatta. È preferibile usare `match_score` + `review_status`.
`target`	boolean \| null	Indica se l’entità è l’oggetto diretto dell’inserimento nella lista.
`review_status`	`Unreviewed` \| `Confirmed Match` \| `False Positive` \| `Inconclusive`	Il valore iniziale deriva dal confronto tra `match_score` e `aml_match_score_threshold`. Modificabile tramite l’endpoint per lo stato dei riscontri AML; il suo aggiornamento attiva un webhook `data.updated` ma non ricalcola automaticamente lo `status` della funzionalità — a tale scopo usa l’endpoint per lo stato AML o la revisione nella console.
`score_breakdown`	object	Modalità di calcolo di `match_score`: punteggi di nome/data di nascita/paese, pesi, contributi ed effetto “golden key” del numero di documento (`MATCH` impone il valore a 100, `NEUTRAL` mantiene il punteggio base, `HARD_MISMATCH` penalizza).
`properties`	object	Attributi grezzi del dataset (nomi, alias, date di nascita, cittadinanza, …). Utile per la valutazione.
`url`	string \| null	URL di origine per l’entità corrispondente, quando disponibile.
`rca_name`	string \| null	Quando il riscontro è un parente o stretto collaboratore (RCA), il nome della persona collegata tramite cui è avvenuta la corrispondenza.
`pep_matches[]`	object[]	Cariche PEP, editori, date di nascita e formazione per il riscontro.
`sanction_matches[]`	object[]	Nome della lista delle sanzioni, programma, autorità sanzionatoria, data di inserimento e URL di origine.
`warning_matches[]`	object[]	Record generici di watchlist o di provvedimenti esecutivi.
`adverse_media_matches[]`	object[]	Notizie negative a livello di articolo: titolo, riassunto, sentiment, URL di origine, data di pubblicazione, parole chiave.
`adverse_media_details`	object \| null	Sentiment aggregato delle notizie negative e conteggio delle parole chiave nell’intero riscontro.
`risk_view`	object	Ripartizione del rischio ponderata per categoria, paese e reato per il riscontro (`risk_level`, `risk_scores`, `weightage`).
`linked_entities[]`	object[]	Entità collegate che il dataset associa al riscontro (ad es. familiari o soci in affari).
`first_seen` / `last_seen`	string \| null	Momento in cui il dataset ha rilevato per la prima/ultima volta questa voce.
`additional_information`	object	Dati aggiuntivi in formato libero forniti dal provider del dataset.

I riscontri classificati come False Positive (perché il match_score è sceso al di sotto della soglia del punteggio di corrispondenza, o perché un revisore li ha contrassegnati) rimangono in hits[] a scopo di audit. Vengono esclusi unicamente dal calcolo del punteggio score aggregato.

Monitoraggio continuo

Quando is_ongoing_monitoring_enabled è true, Didit esegue continuamente un nuovo screening del soggetto e riemette il report AML ogni volta che un hit viene aggiunto, rimosso o modificato. I nuovi screening che modificano lo stato AML attivano un webhook status.updated; i nuovi screening che modificano solo i dati degli hit attivano data.updated. La finestra di monitoraggio decorre da last_aml_bill_date per 365 giorni; next_ongoing_monitoring_bill_date mostra quando scatterà il successivo rinnovo annuale. Questi segnali dipendono tutti dalle variazioni, quindi un soggetto sottoposto a nuovo screening per mesi senza nuovi hit non ne produce alcuno. last_ongoing_screening_at è l’unico campo che si aggiorna a ogni esecuzione completata, e l’endpoint della cronologia dello screening elenca ciascuna esecuzione singolarmente — comprese quelle che non hanno modificato nulla. Consulta Monitoraggio AML continuo per il ciclo di vita completo.

Tre date in questo report hanno tre significati diversi. next_ongoing_monitoring_bill_date indica la prossima data di fatturazione. last_ongoing_screening_at indica quando il soggetto è stato effettivamente sottoposto a screening l’ultima volta. last_ongoing_screening_datasets_updated_at indica quando le liste alla base di tale screening sono state aggiornate l’ultima volta dal provider. Solo la seconda dimostra che il controllo è stato eseguito.

Valori di stato

Valore	Significato
`Not Finished`	Lo screening AML non è ancora stato eseguito per questa sessione/nodo.
`Approved`	Il punteggio complessivo è pari o inferiore alla soglia di approvazione (predefinita `80`) — anche quando non ci sono hit o ogni hit è un `False Positive` (punteggio `0`).
`In Review`	Il punteggio complessivo è superiore alla soglia di approvazione (e pari o inferiore alla soglia di revisione), oppure è stato generato `COULD_NOT_PERFORM_AML_SCREENING`.
`Declined`	Il punteggio complessivo è superiore alla soglia di revisione (predefinita `100`, quindi il rifiuto automatico si verifica solo dopo averla abbassata), oppure lo stato è stato impostato manualmente.

Le soglie sono configurabili per ciascun nodo del workflow — vedi Punteggio di rischio AML. Le regole di stato personalizzate si combinano con lo stato derivato seguendo la precedenza Declined > In Review > Approved; i revisori possono anche sovrascrivere lo stato AML dalla console o dall’endpoint per lo stato AML.

Esempi

Approvato — nessun hit

{
  "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 revisione — hit PEP + hit di notizie negative

Tutti i nomi, gli URL e gli articoli riportati di seguito sono fittizi.

{
  "aml_screenings": [
    {
      "node_id": "aml-1",
      "status": "In Review",
      "total_hits": 1,
      "entity_type": "person",
      "score": 85,
      "hits": [
        {
          "id": "hit_7c1e9a40b2d35f86e0a4c912",
          "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"
        }
      ]
    }
  ]
}

Correlati

Avvisi AML — tutti i codici di avviso che l’AML può emettere
Punteggio di rischio AML e Punteggio di corrispondenza AML — come vengono calcolati i due punteggi
Monitoraggio AML continuo — abilitazione e gestione degli eventi di monitoraggio
Database delle watchlist — dataset coperti
Modelli di dati — Screening AML — schema canonico
Webhook — status.updated viene inviato quando l’AML modifica lo stato della sessione; le modifiche allo stato di revisione degli hit e gli aggiornamenti dei dati di monitoraggio inviano data.updated

Autenticazione

Verifica

Monitoraggio

Piattaforma

Report di screening AML: hit, punteggi e JSON

Panoramica

Dove compare nelle risposte dell’API

Tre punteggi, non un solo verdetto

Schema

Campi per singolo riscontro

Monitoraggio continuo

Valori di stato

Esempi

Approvato — nessun hit

In revisione — hit PEP + hit di notizie negative

Correlati

​Panoramica

​Dove compare nelle risposte dell’API

​Tre punteggi, non un solo verdetto

​Schema

​Campi per singolo riscontro

​Monitoraggio continuo

​Valori di stato

​Esempi

​Approvato — nessun hit

​In revisione — hit PEP + hit di notizie negative

​Correlati

Panoramica

Dove compare nelle risposte dell’API

Tre punteggi, non un solo verdetto

Schema

Campi per singolo riscontro

Monitoraggio continuo

Valori di stato

Esempi

Approvato — nessun hit

In revisione — hit PEP + hit di notizie negative

Correlati