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

# Report di screening AML: hit, punteggi e JSON

> Analizza i report di screening AML di Didit: hit, sanzioni, PEP, notizie negative, punteggi di rischio e corrispondenza e monitoraggio continuo.

## 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](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/aml-screening-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=5b74561abdd242f108fee1b429ff5020)

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

```text theme={null}
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](https://docs.didit.me/it/reference/data-models.md#screening-aml).

## 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](https://docs.didit.me/it/reference/data-models.md#screening-aml) 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](https://docs.didit.me/it/core-technology/aml-screening/warnings-aml-screening.md). |
| `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](https://docs.didit.me/it/core-technology/aml-screening/aml-match-score.md). |
| `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](https://docs.didit.me/it/core-technology/aml-screening/aml-risk-score.md). |
| `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. |

> [!NOTE]
>
> 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](https://docs.didit.me/it/core-technology/aml-screening/continuous-monitoring-aml-screening.md#dimostrare-l’avvenuta-esecuzione-del-monitoraggio) elenca ciascuna esecuzione singolarmente — comprese quelle che non hanno modificato nulla. Consulta [Monitoraggio AML continuo](https://docs.didit.me/it/core-technology/aml-screening/continuous-monitoring-aml-screening.md) per il ciclo di vita completo.

> [!WARNING]
>
> 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](https://docs.didit.me/it/core-technology/aml-screening/aml-risk-score.md). 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

```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,
      "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.

```json theme={null}
{
  "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](https://docs.didit.me/it/core-technology/aml-screening/warnings-aml-screening.md) — tutti i codici di avviso che l'AML può emettere
* [Punteggio di rischio AML](https://docs.didit.me/it/core-technology/aml-screening/aml-risk-score.md) e [Punteggio di corrispondenza AML](https://docs.didit.me/it/core-technology/aml-screening/aml-match-score.md) — come vengono calcolati i due punteggi
* [Monitoraggio AML continuo](https://docs.didit.me/it/core-technology/aml-screening/continuous-monitoring-aml-screening.md) — abilitazione e gestione degli eventi di monitoraggio
* [Database delle watchlist](https://docs.didit.me/it/core-technology/aml-screening/watchlist-database-aml-screening.md) — dataset coperti
* [Modelli di dati — Screening AML](https://docs.didit.me/it/reference/data-models.md#screening-aml) — schema canonico
* [Webhook](https://docs.didit.me/it/integration/webhooks.md) — `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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.