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

# Relatório de triagem AML: hits, pontuações e JSON

> Interprete a triagem AML da Didit: hits, sanções, PEP, mídia adversa, pontuações de risco e correspondência, dados triados e monitoramento contínuo.

## Visão geral

A Análise AML cruza a identidade do titular verificado com bases globais de sanções, PEP, listas de monitoramento e mídia adversa. Cada ocorrência retorna a entidade correspondente, a base de dados ou as bases de dados que geraram a correspondência, duas pontuações (`match_score`, a confiança na identidade, e `risk_score`, o risco da entidade) e um detalhamento estruturado por fonte (`pep_matches[]`, `sanction_matches[]`, `warning_matches[]`, `adverse_media_matches[]`). O `score` agregado é o maior `risk_score` entre as ocorrências que não estão marcadas como `False Positive`.

A Análise AML retorna esse mesmo formato em sessões de usuário (KYC), em sessões de empresa (KYB) e na API AML independente.

![Captura de tela do relatório de Análise AML da Didit com ocorrências de sanções, PEP e mídia adversa](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)

## Onde aparece nas respostas da API

No endpoint de decisão da sessão, a Análise AML é retornada como o array no plural **`aml_screenings[]`**. Cada entrada corresponde a uma execução AML no fluxo de verificação (workflow): uma verificação AML executada duas vezes gera duas entradas com valores de `node_id` diferentes.

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

As sessões AML independentes e de empresa retornam o mesmo formato por registro. Os campos abaixo espelham o schema canônico da página [Modelos de dados](https://docs.didit.me/pt-br/reference/data-models.md#análise-aml).

## Três pontuações, não um único veredito

O `status` é um veredito, e os números dos quais ele foi derivado estão no mesmo payload. Use-os ao montar sua própria classificação de risco em níveis em vez de ramificar apenas em `Approved` / `In Review` / `Declined`. Por exemplo, você pode combinar o risco AML com respostas de questionários, como a origem do patrimônio ou a autodeclaração de PEP:

| Pontuação | Onde | Escala | Responde a |
| - | - | - | - |
| `hits[].match_score` | por ocorrência | 0-100 | A pessoa desta ocorrência é a mesma que foi analisada? Define o `review_status` inicial da ocorrência. |
| `hits[].risk_score` | por ocorrência | 0-100 | Quão arriscada é a entidade correspondente? Determinado pelas categorias da ocorrência (sanção, PEP, crime, ...). |
| `score` | por análise | 0-100 | O maior `risk_score` entre as ocorrências não marcadas como `False Positive`. É com ele que os limiares de aprovação / revisão são comparados para gerar o `status`. |

As três pontuações estão presentes em todos os lugares onde o relatório AML é entregue: `GET /v3/session/{sessionId}/decision/`, o objeto `decision` dos webhooks `status.updated` e `data.updated` em **todas** as versões de webhook (`aml_screenings[]` na V3 e o `aml` no singular nas versões legadas V2 / V1) e a API AML independente. Uma integração que só vê um rótulo de sinalizado / sem sinalização está lendo o `status` (ou o `review_status` de uma ocorrência) e ignorando as pontuações que vêm ao lado. O console mostra os mesmos números: o cabeçalho da seção AML traz a **Risk score** agregada, e cada linha da tabela de correspondências traz a **Match score** e a **Risk score**, com um detalhamento ao passar o mouse.

## Schema

Consulte [Análise AML na referência de modelos de dados](https://docs.didit.me/pt-br/reference/data-models.md#análise-aml) para ver o schema canônico. Campos de nível superior:

| Campo | Tipo | Observações |
| - | - | - |
| `status` | `Not Finished` \| `Approved` \| `Declined` \| `In Review` | Status no nível do recurso (`FeatureStatusChoices`). Orienta as regras do fluxo e a tela de revisão manual. |
| `total_hits` | integer | Número de entradas em `hits[]`. `0` quando não há correspondências. |
| `entity_type` | `person` \| `company` | O tipo de entidade analisada. Empresas e pessoas físicas usam lógicas de correspondência diferentes. |
| `score` | float (0-100) \| null | Pontuação de risco AML agregada: o maior `risk_score` entre os hits não marcados como `False Positive`. `0` quando não há correspondências possíveis; `null` até a análise ser executada. |
| `hits` | `Hit[]` | Uma entrada por registro correspondente, **incluindo** os hits classificados automaticamente como `False Positive` (eles continuam listados, mas ficam fora do `score` agregado). Veja os campos por hit abaixo. |
| `screened_data` | object | Os valores exatos que a Didit enviou para a análise: `full_name`, `date_of_birth`, `nationality` (ISO 3166-1 alpha-2), `document_number`. Útil para explicar um hit a um revisor ou auditar o que foi pesquisado. |
| `is_ongoing_monitoring_enabled` | boolean | `true` depois que você ativa o monitoramento contínuo para a sessão. |
| `next_ongoing_monitoring_bill_date` | string \| null | Data `YYYY-MM-DD` em que ocorre **o faturamento** da próxima renovação anual (`last_aml_bill_date` + 365 dias). `null` até o monitoramento ser ativado. Não é uma data de análise: veja `last_ongoing_screening_at` abaixo. |
| `last_ongoing_screening_at` | string (ISO 8601) \| null | Momento da última das reanálises deste registro **concluídas** pelo monitoramento contínuo, com ou sem mudança no resultado. `null` quando o registro nunca foi reanalisado desde que este campo foi lançado; ele nunca é preenchido retroativamente a partir da data de ativação ou de faturamento. |
| `last_ongoing_screening_datasets_updated_at` | string (ISO 8601) \| null | A data de atualização mais recente dos datasets AML informada pelo provedor no momento dessa análise. `null` quando o provedor não informou datas de datasets; ela nunca é estimada. |
| `warnings` | `Warning[]` | Tags de aviso específicas de AML. Veja [Avisos AML](https://docs.didit.me/pt-br/core-technology/aml-screening/warnings-aml-screening.md). |
| `node_id` | string \| null | Identifica o nó do grafo do fluxo que gerou esta execução AML nas respostas de sessão `/v3/`. A resposta da API AML independente o omite. |

### Campos por hit

Cada entrada em `hits[]` tem os campos a seguir (lista parcial). Os arrays de origem da correspondência (`pep_matches[]`, `sanction_matches[]`, `warning_matches[]`, `adverse_media_matches[]`) são preenchidos apenas para os datasets aos quais o hit pertence.

| Campo | Tipo | Observações |
| - | - | - |
| `id` | string | Identificador estável do hit: `hit_` seguido de 24 caracteres hexadecimais. A mesma entidade correspondente mantém o mesmo `id` quando o sujeito é analisado novamente. Use-o como `hit_id` ao atualizar `review_status` pelo endpoint de status de hit AML. |
| `caption` | string | O nome principal da entidade, como armazenado no dataset. |
| `datasets` | string\[] | Categorias de risco em que a entidade está listada: `PEP` (com seu nível, de `PEP Level 1` a `PEP Level 4`), `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`, `SIP`, `SIE` ou `Insolvency`, e `Other Lists` quando a fonte da entidade não indica nenhuma delas. |
| `match_score` | number (0-100) | Confiança na identidade: a probabilidade de o hit ser a mesma pessoa. Hits abaixo de `aml_match_score_threshold` (padrão `93`) começam como `False Positive`; no limiar ou acima dele, começam como `Unreviewed`. Veja [Pontuação de correspondência AML](https://docs.didit.me/pt-br/core-technology/aml-screening/aml-match-score.md). |
| `risk_score` | number (0-100) | Risco da entidade: o quanto a entidade correspondente é arriscada. O maior `risk_score` entre os hits que não são `False Positive` se torna o `score` de nível superior. Veja [Pontuação de risco AML](https://docs.didit.me/pt-br/core-technology/aml-screening/aml-risk-score.md). |
| `score` | number (0-1) | Pontuação de correspondência ponderada **obsoleta**. Use `match_score` no lugar dela. |
| `match` | boolean \| null | Indicador legado de correspondência exata. Prefira `match_score` + `review_status`. |
| `target` | boolean \| null | Indica se a entidade é o alvo direto da listagem. |
| `review_status` | `Unreviewed` \| `Confirmed Match` \| `False Positive` \| `Inconclusive` | O valor inicial é derivado da comparação entre `match_score` e `aml_match_score_threshold`. Pode ser alterado pelo endpoint de status de hit AML; a atualização dispara um webhook `data.updated`, mas **não** recalcula automaticamente o `status` do recurso. Para isso, use o endpoint de status AML ou a revisão no console. |
| `score_breakdown` | object | Como o `match_score` foi calculado: pontuações de nome, data de nascimento e país, pesos, contribuições e o efeito "chave de ouro" do número do documento (`MATCH` sobrescreve para 100, `NEUTRAL` mantém a pontuação base, `HARD_MISMATCH` penaliza). |
| `properties` | object | Atributos brutos do dataset (nomes, aliases, datas de nascimento, cidadania, …). Úteis para a decisão. |
| `url` | string \| null | URL da fonte da entidade correspondente, quando disponível. |
| `rca_name` | string \| null | Quando o hit é um parente ou associado próximo (RCA), o nome da pessoa relacionada por meio da qual ocorreu a correspondência. |
| `pep_matches[]` | object\[] | Cargos de PEP, publicadores, datas de nascimento e formação do hit. |
| `sanction_matches[]` | object\[] | Nome da lista de sanções, programa, autoridade sancionadora, data de inclusão e URLs das fontes. |
| `warning_matches[]` | object\[] | Registros genéricos de listas de monitoramento ou de ações de fiscalização. |
| `adverse_media_matches[]` | object\[] | Mídia adversa por artigo: manchete, resumo, sentimento, URL da fonte, data de publicação, palavras-chave. |
| `adverse_media_details` | object \| null | Sentimento agregado de mídia adversa e contagens de palavras-chave do hit. |
| `risk_view` | object | Detalhamento do risco do hit ponderado por categoria, país e crime (`risk_level`, `risk_scores`, `weightage`). |
| `linked_entities[]` | object\[] | Entidades relacionadas que o dataset associa ao hit (por exemplo, familiares ou associados comerciais). |
| `first_seen` / `last_seen` | string \| null | Quando o dataset registrou esta entrada pela primeira e pela última vez. |
| `additional_information` | object | Dados extras em formato livre do provedor do dataset. |

> [!NOTE]
>
> Os hits classificados como `False Positive` (porque o `match_score` ficou abaixo do limiar da pontuação de correspondência ou porque um revisor os marcou assim) permanecem em `hits[]` para fins de auditoria. Eles ficam de fora apenas do cálculo do `score` agregado.

### Monitoramento contínuo

Quando `is_ongoing_monitoring_enabled` é `true`, a Didit realiza triagens contínuas da entidade e reemite o relatório AML sempre que um hit é adicionado, removido ou alterado. Novas triagens que mudam o status AML disparam um webhook `status.updated`; novas triagens que mudam apenas os dados dos hits disparam `data.updated`. A janela de monitoramento vai de `last_aml_bill_date` até 365 dias depois; `next_ongoing_monitoring_bill_date` informa quando ocorre a próxima renovação anual.

Todos esses sinais são acionados por mudanças, então uma entidade submetida a novas triagens por meses sem nenhum resultado novo não gera nenhum deles. `last_ongoing_screening_at` é o único campo que muda a **cada** execução concluída, e o [endpoint de histórico de triagens](https://docs.didit.me/pt-br/core-technology/aml-screening/continuous-monitoring-aml-screening.md#comprovando-que-o-monitoramento-rodou) lista cada execução individualmente, incluindo as que não mudaram nada. Consulte [Monitoramento AML contínuo](https://docs.didit.me/pt-br/core-technology/aml-screening/continuous-monitoring-aml-screening.md) para ver o ciclo de vida completo.

> [!WARNING]
>
> Três datas neste relatório significam três coisas diferentes. `next_ongoing_monitoring_bill_date` é quando você será cobrado na próxima vez. `last_ongoing_screening_at` é quando a entidade foi de fato submetida à última triagem. `last_ongoing_screening_datasets_updated_at` é quando as listas usadas nessa triagem foram atualizadas pela última vez pelo provedor. Apenas a segunda comprova que o controle foi executado.

## Valores de status

| Valor | Significado |
| - | - |
| `Not Finished` | A análise AML ainda não foi executada para esta sessão ou nó. |
| `Approved` | A pontuação agregada é igual ou inferior ao limiar de aprovação (padrão `80`), inclusive quando não há resultados ou todos os resultados são `False Positive` (pontuação `0`). |
| `In Review` | A pontuação agregada está acima do limiar de aprovação (e igual ou inferior ao limiar de revisão), ou `COULD_NOT_PERFORM_AML_SCREENING` foi disparado. |
| `Declined` | A pontuação agregada está acima do limiar de revisão (padrão `100`, então a recusa automática só acontece depois que você o reduz), ou o status foi definido manualmente. |

Os limiares são configuráveis por nó do fluxo de verificação (workflow); consulte [Pontuação de risco AML](https://docs.didit.me/pt-br/core-technology/aml-screening/aml-risk-score.md). Regras de status personalizadas se combinam com o status derivado seguindo a precedência `Declined` > `In Review` > `Approved`; os revisores também podem substituir o status AML no console ou pelo endpoint de status AML.

## Exemplos

### Aprovado: sem correspondências

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

### Em revisão: correspondência de PEP + mídia adversa

Todos os nomes, URLs e artigos abaixo são fictícios.

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

## Relacionados

* [Avisos AML](https://docs.didit.me/pt-br/core-technology/aml-screening/warnings-aml-screening.md): todos os códigos de aviso que a análise AML pode emitir
* [Pontuação de risco AML](https://docs.didit.me/pt-br/core-technology/aml-screening/aml-risk-score.md) e [pontuação de correspondência AML](https://docs.didit.me/pt-br/core-technology/aml-screening/aml-match-score.md): como as duas pontuações são calculadas
* [Monitoramento AML contínuo](https://docs.didit.me/pt-br/core-technology/aml-screening/continuous-monitoring-aml-screening.md): como ativar e consumir eventos de monitoramento
* [Banco de dados de listas de monitoramento](https://docs.didit.me/pt-br/core-technology/aml-screening/watchlist-database-aml-screening.md): conjuntos de dados cobertos
* [Modelos de dados: análise AML](https://docs.didit.me/pt-br/reference/data-models.md#análise-aml): schema canônico
* [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md): `status.updated` é disparado quando a análise AML altera o status da sessão; mudanças no status de revisão dos resultados e atualizações dos dados de monitoramento disparam `data.updated`


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