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

# Rapport de filtrage AML : correspondances, scores et JSON

> Analysez les rapports de filtrage AML Didit : correspondances, sanctions, PEP, presse négative, scores de risque et surveillance continue.

## Vue d'ensemble

Le filtrage AML recoupe l'identité du sujet vérifié avec des jeux de données mondiaux de sanctions, de PEP, de listes de surveillance et de presse négative. Chaque occurrence renvoie l'entité correspondante, le ou les jeux de données à l'origine de la correspondance, deux scores — `match_score` (confiance dans l'identité) et `risk_score` (risque lié à l'entité) — ainsi qu'une ventilation structurée par source (`pep_matches[]`, `sanction_matches[]`, `warning_matches[]`, `adverse_media_matches[]`). Le `score` global correspond au `risk_score` le plus élevé parmi les résultats qui ne sont pas marqués comme `False Positive`.

Le même format est renvoyé par le filtrage AML sur les sessions d'utilisateurs (KYC), les sessions d'entreprises (KYB) et l'API AML autonome.

![Capture d'écran du rapport de filtrage AML Didit avec des correspondances de sanctions, PEP et presse négative](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)

## Où il apparaît dans les réponses d'API

Sur l'endpoint de décision de la session, le filtrage AML est renvoyé sous la forme d'un tableau au pluriel **`aml_screenings[]`**. Chaque entrée correspond à une exécution AML dans le workflow (un contrôle AML exécuté deux fois génère deux entrées avec des valeurs de `node_id` différentes).

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

L'API AML autonome et les sessions d'entreprise renvoient la même structure par enregistrement. Les champs ci-dessous reflètent le schéma canonique de la page [Modèles de données](https://docs.didit.me/fr/reference/data-models.md#filtrage-aml).

## Trois scores, pas un seul verdict

Le champ `status` est un verdict ; les chiffres dont il découle se trouvent dans le même payload. Consultez-les lorsque vous construisez votre propre segmentation des risques (par exemple en combinant le risque AML avec les réponses à un questionnaire telles que l'origine du patrimoine ou l'auto-déclaration PEP) au lieu de vous baser uniquement sur `Approved` / `In Review` / `Declined` :

| Score | Emplacement | Échelle | Réponses |
| - | - | - | - |
| `hits[].match_score` | par occurrence | 0-100 | Cette occurrence concerne-t-elle la même personne que celle filtrée ? Détermine le `review_status` initial de l'occurrence. |
| `hits[].risk_score` | par occurrence | 0-100 | Quel est le niveau de risque de l'entité correspondante ? Déterminé par les catégories de l'occurrence (sanctions, PEP, criminalité, ...). |
| `score` | par filtrage | 0-100 | Le `risk_score` le plus élevé parmi les correspondances non marquées comme `False Positive`. C'est à cette valeur que sont comparés les seuils d'approbation et d'examen pour générer le `status`. |

Tous les trois sont présents à chaque endroit où le rapport AML est délivré : `GET /v3/session/{sessionId}/decision/`, l'objet `decision` des webhooks `status.updated` et `data.updated` sur **toutes** les versions de webhook (au pluriel `aml_screenings[]` en V3, et au singulier `aml` dans les versions héritées en V2 / V1), ainsi que sur l'API AML autonome. Un consommateur qui ne voit qu'un libellé signalé / clair lit `status` (ou le `review_status` d'une correspondance) et ignore les scores situés juste à côté. La console affiche les mêmes chiffres : l'en-tête de la section AML présente le **Score de risque** global, et chaque ligne du tableau des correspondances affiche le **Score de correspondance** et le **Score de risque** avec un détail au survol.

## Schéma

Consultez [Filtrage AML dans la référence des modèles de données](https://docs.didit.me/fr/reference/data-models.md#filtrage-aml) pour le schéma canonique. Champs de premier niveau :

| Champ | Type | Notes |
| - | - | - |
| `status` | `Not Finished` \| `Approved` \| `Declined` \| `In Review` | Statut au niveau de la fonctionnalité (`FeatureStatusChoices`). Pilote les règles de workflow et l'écran d'examen manuel. |
| `total_hits` | integer | Nombre d'entrées dans `hits[]`. `0` lorsqu'il n'y a aucune correspondance. |
| `entity_type` | `person` \| `company` | Le type de sujet filtré. Les entreprises et les personnes physiques utilisent une logique de correspondance différente. |
| `score` | float (0-100) \| null | Score de risque AML agrégé — le `risk_score` le plus élevé parmi les correspondances non marquées comme `False Positive`. `0` lorsqu'il n'y a aucune correspondance possible ; `null` tant que le filtrage n'a pas été exécuté. |
| `hits` | `Hit[]` | Une entrée par enregistrement correspondant, **y compris** les correspondances automatiquement classées comme `False Positive` (elles restent listées mais sont exclues du `score` agrégé). Consultez les champs par correspondance ci-dessous. |
| `screened_data` | object | Les valeurs exactes envoyées par Didit au filtrage : `full_name`, `date_of_birth`, `nationality` (ISO 3166-1 alpha-2), `document_number`. Utile pour expliquer une correspondance à un réviseur ou auditer ce qui a été recherché. |
| `is_ongoing_monitoring_enabled` | boolean | `true` une fois que vous activez la surveillance continue pour la session. |
| `next_ongoing_monitoring_bill_date` | string \| null | `YYYY-MM-DD` du prochain renouvellement annuel de **la facturation** (`last_aml_bill_date` + 365 jours). `null` tant que la surveillance n'est pas activée. Il ne s'agit pas d'une date de filtrage — voir `last_ongoing_screening_at` ci-dessous. |
| `last_ongoing_screening_at` | string (ISO 8601) \| null | Moment où la surveillance continue a **terminé pour la dernière fois le nouveau filtrage** de cet enregistrement, que le résultat ait changé ou non. `null` lorsque l'enregistrement n'a jamais fait l'objet d'un nouveau filtrage depuis l'introduction de ce champ — il n'est jamais renseigné rétroactivement à partir de la date d'activation ou de facturation. |
| `last_ongoing_screening_datasets_updated_at` | string (ISO 8601) \| null | La date de mise à jour des jeux de données AML la plus récente signalée par le fournisseur au moment de ce filtrage. `null` lorsque le fournisseur n'a indiqué aucune date de jeu de données ; elle n'est jamais estimée. |
| `warnings` | `Warning[]` | Tags d'avertissement spécifiques à l'AML. Consultez [Avertissements AML](https://docs.didit.me/fr/core-technology/aml-screening/warnings-aml-screening.md). |
| `node_id` | string \| null | Identifie le nœud du graphe de workflow ayant produit cette exécution AML sur les réponses de session `/v3/`. La réponse de l'API AML autonome l'omet. |

### Champs par correspondance

Chaque entrée de `hits[]` comporte les champs suivants (extrait affiché). Les tableaux de sources de correspondance — `pep_matches[]`, `sanction_matches[]`, `warning_matches[]`, `adverse_media_matches[]` — ne sont renseignés que pour le ou les jeux de données auxquels appartient la correspondance.

| Champ | Type | Notes |
| - | - | - |
| `id` | string | Identifiant stable de correspondance : `hit_` suivi de 24 caractères hexadécimaux. La même entité correspondante conserve le même `id` lorsque le sujet est filtré à nouveau. Utilisez-le comme `hit_id` lors de la mise à jour de `review_status` via l'endpoint de statut de correspondance AML. |
| `caption` | string | Le nom principal de l'entité tel qu'enregistré dans le jeu de données. |
| `datasets` | string\[] | Catégories de risque sous lesquelles l'entité est répertoriée : `PEP` (avec son niveau, de `PEP Level 1` à `PEP Level 4`), `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`, `SIP`, `SIE` ou `Insolvency`, et `Other Lists` lorsque la source de l'entité n'en mentionne aucune. |
| `match_score` | number (0-100) | Score de confiance sur l'identité — probabilité que la correspondance concerne la même personne. Les correspondances inférieures à `aml_match_score_threshold` (par défaut `93`) sont initialement classées comme `False Positive` ; à ce seuil ou au-dessus, elles sont initialement classées comme `Unreviewed`. Consultez [Score de correspondance AML](https://docs.didit.me/fr/core-technology/aml-screening/aml-match-score.md). |
| `risk_score` | number (0-100) | Risque lié à l'entité — niveau de risque de l'entité correspondante. Le `risk_score` le plus élevé parmi les correspondances autres que `False Positive` devient le `score` de premier niveau. Consultez [Score de risque AML](https://docs.didit.me/fr/core-technology/aml-screening/aml-risk-score.md). |
| `score` | number (0-1) | Score de correspondance pondéré **obsolète**. Utilisez plutôt `match_score`. |
| `match` | boolean \| null | Indicateur hérité de correspondance exacte. Privilégiez `match_score` + `review_status`. |
| `target` | boolean \| null | Indique si l'entité est la cible directe de l'inscription sur la liste. |
| `review_status` | `Unreviewed` \| `Confirmed Match` \| `False Positive` \| `Inconclusive` | La valeur initiale est dérivée de `match_score` par rapport à `aml_match_score_threshold`. Modifiable via l'endpoint de statut de correspondance AML ; sa mise à jour déclenche un webhook `data.updated`, mais ne recalcule **pas** automatiquement le `status` de la fonctionnalité — utilisez l'endpoint de statut AML ou l'examen dans la console pour cela. |
| `score_breakdown` | object | Manière dont `match_score` a été calculé : scores de nom/DOB/pays, pondérations, contributions, et effet « golden key » du numéro de document (`MATCH` force la valeur à 100, `NEUTRAL` conserve le score de base, `HARD_MISMATCH` applique une pénalité). |
| `properties` | object | Attributs bruts du jeu de données (noms, alias, dates de naissance, citoyenneté, …). Utile pour l'arbitrage. |
| `url` | string \| null | URL source de l'entité correspondante, lorsqu'elle est disponible. |
| `rca_name` | string \| null | Lorsque la correspondance est un proche ou associé (RCA), le nom de la personne liée par laquelle la correspondance a été établie. |
| `pep_matches[]` | object\[] | Fonctions PEP, éditeurs, dates de naissance et formation pour la correspondance. |
| `sanction_matches[]` | object\[] | Nom de la liste de sanctions, programme, autorité de sanction, date d'inscription sur la liste et URLs sources. |
| `warning_matches[]` | object\[] | Enregistrements génériques de listes de surveillance ou de mesures d'exécution réglementaire. |
| `adverse_media_matches[]` | object\[] | Presse négative au niveau de l'article : titre, résumé, tonalité, URL source, date de publication, mots-clés. |
| `adverse_media_details` | object \| null | Tonalité globale de la presse négative et décompte des mots-clés pour l'ensemble de la correspondance. |
| `risk_view` | object | Détail du risque pondéré par catégorie, pays et criminalité pour la correspondance (`risk_level`, `risk_scores`, `weightage`). |
| `linked_entities[]` | object\[] | Entités liées que le jeu de données associe à la correspondance (par exemple, membres de la famille ou associés professionnels). |
| `first_seen` / `last_seen` | string \| null | Date et heure auxquelles le jeu de données a observé cette entrée pour la première/dernière fois. |
| `additional_information` | object | Informations supplémentaires au format libre fournies par le fournisseur du jeu de données. |

> [!NOTE]
>
> Les correspondances classées comme `False Positive` (parce que leur `match_score` était inférieur au seuil du score de correspondance ou parce qu'un réviseur les a marquées ainsi) restent dans `hits[]` pour permettre l'audit. Elles sont uniquement exclues du calcul du `score` agrégé.

### Surveillance continue

Lorsque `is_ongoing_monitoring_enabled` est défini sur `true`, Didit filtre à nouveau le sujet en continu et réémet le rapport AML chaque fois qu'un résultat est ajouté, supprimé ou modifié. Les nouveaux filtrages qui modifient le statut AML déclenchent un webhook `status.updated` ; les nouveaux filtrages qui modifient uniquement les données des résultats déclenchent `data.updated`. La période de surveillance court à partir de la date `last_aml_bill_date` pendant 365 jours ; `next_ongoing_monitoring_bill_date` indique la date du prochain renouvellement annuel.

Ces signaux sont tous déclenchés par des changements, de sorte qu'un sujet refiltré pendant des mois sans nouveau résultat n'en produit aucun. `last_ongoing_screening_at` est le seul champ mis à jour à **chaque** exécution terminée, et l'[endpoint screening-history](https://docs.didit.me/fr/core-technology/aml-screening/continuous-monitoring-aml-screening.md#prouver-que-la-surveillance-a-bien-été-exécutée) liste chaque exécution individuellement — y compris celles qui n'ont rien modifié. Consultez [Surveillance AML continue](https://docs.didit.me/fr/core-technology/aml-screening/continuous-monitoring-aml-screening.md) pour découvrir l'ensemble du cycle de vie.

> [!WARNING]
>
> Trois dates sur ce rapport ont des significations différentes. `next_ongoing_monitoring_bill_date` correspond à votre prochaine facturation. `last_ongoing_screening_at` correspond à la dernière date à laquelle le sujet a réellement été filtré. `last_ongoing_screening_datasets_updated_at` correspond à la dernière mise à jour par le fournisseur des listes utilisées pour ce filtrage. Seule la deuxième atteste que le contrôle a bien été exécuté.

## Valeurs de statut

| Valeur | Signification |
| - | - |
| `Not Finished` | L'AML n'a pas encore été exécuté pour cette session/ce nœud. |
| `Approved` | Le score global est inférieur ou égal au seuil d'approbation (par défaut `80`) — y compris lorsqu'il n'y a aucun résultat ou que chaque résultat est un `False Positive` (score `0`). |
| `In Review` | Le score global est supérieur au seuil d'approbation (et inférieur ou égal au seuil d'examen), ou `COULD_NOT_PERFORM_AML_SCREENING` a été déclenché. |
| `Declined` | Le score global est supérieur au seuil d'examen (par défaut `100`, le refus automatique n'intervient donc que si vous l'abaissez), ou le statut a été défini manuellement. |

Les seuils sont configurables par nœud de workflow — consultez [Score de risque AML](https://docs.didit.me/fr/core-technology/aml-screening/aml-risk-score.md). Les règles de statut personnalisées se combinent avec le statut dérivé selon l'ordre de priorité `Declined` > `In Review` > `Approved` ; les réviseurs peuvent également remplacer le statut AML depuis la console ou via l'endpoint de statut AML.

## Exemples

### Approved — aucun résultat

```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 Review — résultat PEP + presse négative

Tous les noms, URL et articles ci-dessous sont fictifs.

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

## Ressources associées

* [Avertissements AML](https://docs.didit.me/fr/core-technology/aml-screening/warnings-aml-screening.md) — tous les codes d'avertissement que l'AML peut émettre
* [Score de risque AML](https://docs.didit.me/fr/core-technology/aml-screening/aml-risk-score.md) et [Score de correspondance AML](https://docs.didit.me/fr/core-technology/aml-screening/aml-match-score.md) — mode de calcul des deux scores
* [Surveillance AML continue](https://docs.didit.me/fr/core-technology/aml-screening/continuous-monitoring-aml-screening.md) — activation et traitement des événements de surveillance
* [Base de données des listes de surveillance](https://docs.didit.me/fr/core-technology/aml-screening/watchlist-database-aml-screening.md) — jeux de données couverts
* [Modèles de données — Filtrage AML](https://docs.didit.me/fr/reference/data-models.md#filtrage-aml) — schéma canonique
* [Webhooks](https://docs.didit.me/fr/integration/webhooks.md) — `status.updated` se déclenche lorsque l'AML modifie le statut de la session ; les changements de statut d'examen des résultats et les actualisations des données de surveillance déclenchent `data.updated`


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