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

# AML Screening Overview

> Screen users against 1,300+ global sanctions, PEP, and watchlist databases in real time. Pay-per-call $0.20, two-score risk system, no contracts.

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

export const VideoEmbed = ({src, title = "Video", type = "iframe"}) => <div className={type === "iframe" ? "didit-video-embed" : "didit-video-embed didit-video-native"}>
    {type === "iframe" ? <iframe src={src} title={title} style={{
  width: "100%",
  height: "100%",
  border: 0,
  borderRadius: "12px"
}} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen /> : <video controls autoPlay muted loop playsInline src={src} title={title} style={{
  width: "100%",
  height: "auto",
  display: "block",
  borderRadius: "12px"
}} />}
  </div>;

Didit's AML Screening provides real-time risk detection by screening users against global watchlists and databases. The solution combines advanced data matching with AI-powered risk assessment to ensure regulatory compliance while maintaining a smooth user experience.

<AgentPromptAccordion
  title="AML Screening Integration Prompt"
  prompt={`# Goal
Integrate Didit AML Screening (PEP, sanctions, warnings, adverse media) into your app. Pick ONE mode.

# Mode A — Session-based
Run AML as a step inside a verification session. Decisions, ongoing monitoring, and audit history are bound to the session and surfaced in the Business Console.

1. Add the AML feature to the workflow (Business Console or POST /v3/workflows/). Configure thresholds: aml_match_score_threshold, aml_score_approve_threshold, aml_score_review_threshold, and the weights aml_name_weight + aml_dob_weight + aml_country_weight (must sum to 100).
2. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: \`aml_screenings[]\` array on the decision payload.

# Mode B — Standalone API (server-to-server)
Use when you want a one-shot AML check decoupled from a hosted KYC flow.

POST https://verification.didit.me/v3/aml/
x-api-key: YOUR_API_KEY
Content-Type: application/json

curl example:
\`\`\`bash
curl -X POST 'https://verification.didit.me/v3/aml/' \\
-H "x-api-key: $DIDIT_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"full_name": "Javier Ejemplo Modelo",
"entity_type": "person",
"date_of_birth": "1974-01-01",
"nationality": "ES",
"include_adverse_media": true,
"vendor_data": "user-1234"
}'
\`\`\`
Returns: { request_id, aml: { status, screening_id, hits: [...], warnings: [...] } }.

# Important policy rules
- aml_name_weight + aml_dob_weight + aml_country_weight must equal exactly 100 — request rejected with HTTP 400 otherwise.
- include_adverse_media=true increases latency to ~25s; use a client timeout of at least 45s.
- include_ongoing_monitoring=true keeps the entity under daily re-screening at **$0.07 per year per screened entity** (billing alert) and requires save_api_request=true (HTTP 400 otherwise). Disable from the Business Console.

# Status enum (per aml_screenings[].status / aml.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

# Warnings (LogWarningChoices.AML)
warnings[] risk codes include:
POSSIBLE_MATCH_FOUND, MATCH_FOUND, HIGH_RISK_COUNTRY, ADVERSE_MEDIA_HIT, SANCTIONED_ENTITY, PEP_MATCH, ONGOING_MONITORING_ENABLED.
Full catalogue: /core-technology/aml-screening/warnings-aml-screening.

# Failure modes to handle
- HTTP 400 — weights don't sum to 100; ongoing_monitoring without save_api_request.
- HTTP 403 — out of credits.
- status="Declined" — at least one hit's risk_score ≥ aml_score_review_threshold and crossed the decline boundary.
- status="In Review" — risk_score between approve and review thresholds; route to manual queue.
- Adverse-media timeout — the upstream provider was slow; the result returns without adverse-media hits (still actionable).

# See also
- Canonical schema: /reference/data-models#aml-screening
- Per-feature report: /core-technology/aml-screening/report-aml-screening
- Risk catalogue: /core-technology/aml-screening/warnings-aml-screening
- Ongoing monitoring: /core-technology/aml-screening/continuous-monitoring-aml-screening
- Full integration playbook: /integration/integration-prompt`}
/>

<VideoEmbed src="https://www.youtube.com/embed/h0i9Q0-izcw?start=654&rel=0&playsinline=1" title="AML Screening: PEPs, Sanctions, and Match Scores" />

<Frame>
  <img src="https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/aml-list-table.jpeg?fit=max&auto=format&n=z6T2GHM4Zh-iSj-K&q=85&s=b254abf5bb564018e15588ef7c56f92e" alt="Didit AML screening watchlist sources table including OFAC, EU, UN sanctions and PEP lists" width="1280" height="713" data-path="images/aml-list-table.jpeg" />
</Frame>

## Key Concepts: Match Score vs Risk Score

Didit uses a **two-score system** for AML screening:

### Match Score (Identity Confidence)

* **Question:** Is this match the same person we're screening?
* **Factors:** Name similarity, Date of Birth, Country/Nationality, Document Number
* **Purpose:** Classifies match as **False Positive** or **Unreviewed** (Possible Match)
* **Threshold:** Match Score Threshold (default: 93)

### Risk Score (Entity Risk Level)

* **Question:** How risky is this entity if it's a true match?
* **Factors:** Country risk, Category (PEP/Sanctions/etc.), Criminal records
* **Purpose:** Determines the **final AML status** (Approved/In Review/Declined)
* **Thresholds:** Approve Threshold (default: 80) and Review Threshold (default: 100)

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           AML SCREENING FLOW                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  STEP 1: Screen against watchlists                                          │
│     └── Returns potential matches (match score ≥ 75% included)              │
│                                                                             │
│  STEP 2: For each match, calculate MATCH SCORE                              │
│     └── Match Score = (Name × W1) + (DOB × W2) + (Country × W3)             │
│                                                                             │
│  STEP 3: Classify match by match score                                      │
│     ├── Match Score < 93 → FALSE POSITIVE (excluded from risk)              │
│     └── Match Score ≥ 93 → UNREVIEWED (included in risk)                    │
│                                                                             │
│  STEP 4: For unreviewed matches, calculate RISK SCORE                       │
│     └── Risk Score = (Country × 30%) + (Category × 50%) + (Criminal × 20%)  │
│                                                                             │
│  STEP 5: Determine AML STATUS (highest risk score among non-FP matches)     │
│     ├── Risk Score < 86 → APPROVED                                          │
│     ├── 86 ≤ Risk Score ≤ 100 → IN REVIEW                                   │
│     └── Risk Score > 100 → DECLINED                                         │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Match Review Statuses

Each AML match is assigned a review status based on its match score:

| Status              | Description                                     | When Assigned                            |
| ------------------- | ----------------------------------------------- | ---------------------------------------- |
| **False Positive**  | Match is likely NOT the same person             | Match score \< threshold (auto-assigned) |
| **Unreviewed**      | Match is a possible match requiring review      | Match score ≥ threshold (auto-assigned)  |
| **Confirmed Match** | Match has been verified as the same person      | Manually set by compliance officer       |
| **Inconclusive**    | Unable to determine if match is the same person | Manually set by compliance officer       |

<Note>
  ### **Tip:** You can change a match review status in the Console by viewing the AML overview or clicking on a specific match to see its details.
</Note>

## Key Features

### 1. Comprehensive Data Extraction

* **Accurate Extraction**: Extract data from user-provided information or identity documents using advanced OCR technology.
* **Fuzzy Logic**: Account for name variations and misspellings to ensure comprehensive data capture.

### 2. Extensive Watchlist Coverage

Screen against multiple categories including:

* **Sanctions Lists**: From government and international bodies.
* **Politically Exposed Persons (PEPs)**: Individuals with prominent public functions.
* **Criminal Records**: Including global and local criminal databases.
* **Adverse Media Mentions**: News articles and reports on financial crimes and other risks.
* **Custom Watchlists**: Configurable based on specific client requirements.

### 3. Advanced Matching Algorithms

* **Fuzzy Matching**: Catch slight variations in names or details to ensure accurate matching.
* **Multiple Data Points**: Utilize name, date of birth, nationality, and other identifiers for thorough screening.
* **Golden Key Logic**: Document number matching that can override scores for definitive identification.

### 4. Two-Score Risk Assessment

Each match receives TWO scores:

| Score                   | Purpose                   | Classification               |
| ----------------------- | ------------------------- | ---------------------------- |
| **Match Score** (0-100) | Is this the same person?  | False Positive vs Unreviewed |
| **Risk Score** (0-100)  | How risky is this entity? | Determines final AML status  |

**Match Review Status (based on Match Score):**

* **False Positive**: Match score below threshold - likely NOT the same person
* **Unreviewed**: Match score at or above threshold - requires review

**Final AML Status (based on highest Risk Score among non-false-positive matches):**

* **Approved**: All unreviewed matches have low risk scores
* **In Review**: At least one unreviewed match has medium-high risk score
* **Declined**: At least one unreviewed match has very high risk score

### 5. Detailed Adverse Media Screening

Screen against a wide range of adverse media categories, including:

* **Financial Crimes**: Money laundering, embezzlement, and more.
* **Violent Crimes**: Assault, murder, and related offenses.
* **Terrorism**: Involvement in or support for terrorist activities.
* **Narcotics**: Drug trafficking and related crimes.
* **Fraud**: Various types of fraud and deceptive practices.
* **Regulatory Violations**: Breaches of regulatory compliance requirements.

### 6. Customizable Screening Parameters

* **Adjustable Sensitivity**: Configure the screening sensitivity based on your organization's risk appetite.
* **Customizable Watchlists**: Select which watchlists and categories to include in the screening process to meet specific requirements.

### Configurable Thresholds

You can customize security levels by setting different thresholds:

**Match Score Configuration:**

| Setting               | Default | Description                                                        |
| --------------------- | ------- | ------------------------------------------------------------------ |
| Match Score Threshold | 93      | Matches below this are False Positives, at or above are Unreviewed |
| Name Weight           | 60      | Weight for name in match score                                     |
| DOB Weight            | 25      | Weight for DOB in match score                                      |
| Country Weight        | 15      | Weight for country in match score                                  |

**Risk Score Thresholds (Final Status):**

| Setting           | Default | Description                                       |
| ----------------- | ------- | ------------------------------------------------- |
| Approve Threshold | 80      | Risk scores below = Approved                      |
| Review Threshold  | 100     | Risk scores above = Declined; between = In Review |

<Frame>
  <img src="https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/aml-risk-score.png?fit=max&auto=format&n=z6T2GHM4Zh-iSj-K&q=85&s=297acc5d98dcd0f038597c4f2d953f46" alt="Didit AML risk score thresholds for Approved, In Review and Declined statuses" width="818" height="466" data-path="images/aml-risk-score.png" />
</Frame>

<Note>
  These thresholds can be adjusted based on your risk tolerance and security requirements.
</Note>

## How It Works

Our AML Screening process efficiently identifies potential risks while minimizing delays for legitimate users.

<Steps>
  <Step title="Data Extraction" icon="file-lines">
    The system extracts relevant information from either user-provided data or uploaded identity documents.

    | Input                  | Method                                                 |
    | ---------------------- | ------------------------------------------------------ |
    | **Identity documents** | Advanced OCR technology for accurate data extraction   |
    | **User-provided data** | Direct input (name, DOB, nationality, document number) |
    | **Fuzzy logic**        | Accounts for name variations and misspellings          |
  </Step>

  <Step title="Watchlist Screening" icon="magnifying-glass">
    The extracted data is cross-checked against **1,300+ global watchlists** and databases in real time:

    * **Sanctions Lists** — Government and international bodies (OFAC, EU, UN, etc.)
    * **Politically Exposed Persons (PEPs)** — Individuals with prominent public functions
    * **Criminal Records** — Global and local criminal databases
    * **Adverse Media** — News articles and reports on financial crimes
    * **Custom Watchlists** — Configurable based on your requirements
  </Step>

  <Step title="Match Score Calculation" icon="calculator">
    For each potential match, the system calculates an **identity confidence score** — how likely it is the same person.

    | Factor                  | Default Weight | Description                              |
    | ----------------------- | :------------: | ---------------------------------------- |
    | **Name similarity**     |       60%      | Fuzzy matching accounting for variations |
    | **Date of Birth**       |       25%      | Exact or partial DOB comparison          |
    | **Country/Nationality** |       15%      | Country of origin comparison             |

    * Match Score **below threshold** (default: 93) → classified as **False Positive**
    * Match Score **at or above threshold** → classified as **Unreviewed** (possible match)
    * **Golden Key**: Document number match can override to 100% for definitive identification
  </Step>

  <Step title="Risk Score Calculation" icon="triangle-exclamation">
    For non-false-positive matches, the system calculates the entity's **risk level**:

    | Factor               | Weight | Description                                  |
    | -------------------- | :----: | -------------------------------------------- |
    | **Category**         |   50%  | PEP level, sanctions type, criminal severity |
    | **Country risk**     |   30%  | Risk rating of associated countries          |
    | **Criminal records** |   20%  | Presence and severity of criminal history    |
  </Step>

  <Step title="Final Status Determination" icon="gavel">
    Based on the **highest risk score** among all non-false-positive matches:

    |        Risk Score       | Status        | Action                               |
    | :---------------------: | ------------- | ------------------------------------ |
    | Below approve threshold | **Approved**  | Auto-cleared, no credible risk       |
    |    Between thresholds   | **In Review** | Flagged for manual compliance review |
    |  Above review threshold | **Declined**  | High risk, automatic rejection       |

    If **all** matches are false positives, the result is **Approved** (no credible matches found).
  </Step>

  <Step title="Result Generation" icon="file-export">
    A detailed report is generated with full transparency:

    * Each match's **match score** and **risk score** with breakdowns
    * Match classification (False Positive vs. Unreviewed vs. Confirmed)
    * Source database and category details for every hit
    * Results delivered via **API response**, **webhook**, or **Business Console**
    * Automatic decisioning based on your configured risk score thresholds
  </Step>
</Steps>

## AML Hit Data Reference

Each AML hit returned in the API response contains detailed information about the matched entity. Below are the key fields and their possible values.

### Dataset Categories

The `datasets` field on each hit indicates which compliance database categories the entity was found in. Possible values:

| Value                                 | Description                                                     |
| ------------------------------------- | --------------------------------------------------------------- |
| `PEP`                                 | Politically Exposed Person (general)                            |
| `PEP Level 1`                         | Heads of state, senior politicians, supreme court judges        |
| `PEP Level 2`                         | Members of parliament, ambassadors, military leaders            |
| `PEP Level 3`                         | Local government officials, mid-level civil servants            |
| `PEP Level 4`                         | RCA (Relatives and Close Associates) of PEP individuals         |
| `Sanctions`                           | International and national sanctions lists (OFAC, EU, UN, etc.) |
| `Adverse Media`                       | Negative news articles and reports related to financial crime   |
| `Warnings and Regulatory Enforcement` | Regulatory warnings, enforcement actions, and compliance alerts |
| `Fitness and Probity`                 | Fitness and probity registers from financial regulators         |
| `SIP`                                 | Special Interest Person lists                                   |
| `SIE`                                 | Special Interest Entity lists                                   |
| `Insolvency`                          | Insolvency and bankruptcy registers                             |

### Sanction Matches

The `sanction_matches` array contains details for each sanction list where the entity was found. Key fields:

| Field                   | Type       | Description                                                                                                                                                                                                                                                                       |
| ----------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_name`             | `string[]` | Name(s) of the sanction list(s)                                                                                                                                                                                                                                                   |
| `matched_name`          | `string`   | Name as it appears in the sanction list                                                                                                                                                                                                                                           |
| `description`           | `string`   | Description of the sanction entry                                                                                                                                                                                                                                                 |
| `reason`                | `string`   | Free-text reason why the entity was sanctioned. This is not an enum — values come directly from the sanctioning authority and describe the specific grounds for the listing (e.g., "Executive Order 13224 (Terrorism)", "Support for actions undermining Ukraine's sovereignty"). |
| `legal_basis`           | `string[]` | Legal basis for the sanction                                                                                                                                                                                                                                                      |
| `sanction_program`      | `string[]` | Sanction program(s) the entity is listed under                                                                                                                                                                                                                                    |
| `sanctioning_authority` | `string[]` | Authority that imposed the sanction                                                                                                                                                                                                                                               |
| `listed_on`             | `string[]` | Date(s) when the entity was listed                                                                                                                                                                                                                                                |
| `source_url`            | `string`   | URL to the source                                                                                                                                                                                                                                                                 |

### Warning Matches

The `warning_matches` array contains details for matches from warning, regulatory enforcement, and related lists. The `additional_data` field may include a `data.case_details` array with structured case information.

#### Warning Case Types

The `case_type` field within `additional_data.data.case_details[]` describes the nature of the warning case. Known values:

| Value                       | Description                                  |
| --------------------------- | -------------------------------------------- |
| `Accusation`                | Formal accusation or charge                  |
| `Arrest`                    | Arrest record                                |
| `Bribery`                   | Bribery-related case                         |
| `Criminal`                  | General criminal case                        |
| `Fraud`                     | Fraud-related case                           |
| `Illegal Fundraising`       | Illegal fundraising activity                 |
| `Non-conviction Terror`     | Terrorism-related listing without conviction |
| `Proclaimed Offender`       | Officially proclaimed offender               |
| `Regulatory Enforcement`    | Regulatory enforcement action                |
| `Terrorism`                 | Terrorism-related case                       |
| `Terrorism-related`         | Related to terrorism activities              |
| `Terrorism-related listing` | Listed in connection with terrorism          |
