didit-aml-screening

集成 Didit AML Screening 独立 API 以筛选个人或公司 全球观察名单。当用户想要执行 AML 检查、筛查制裁时使用 列出、检查 PEP 状态、检测不良媒体、实施 KYC/AML 合规性、筛查 OFAC/UN/EU 观察名单、计算风险评分或执行反洗钱筛查 使用迪迪特。支持1300+数据库，模糊名称匹配，可配置评分权重， 和持续监测。

## 概述（中文）

集成 Didit AML Screening 独立 API 以筛选个人或公司
全球观察名单。当用户想要执行 AML 检查、筛查制裁时使用
列出、检查 PEP 状态、检测不良媒体、实施 KYC/AML 合规性、筛查
OFAC/UN/EU 观察名单、计算风险评分或执行反洗钱筛查
使用迪迪特。支持1300+数据库，模糊名称匹配，可配置评分权重，
和持续监测。

## 原文

# Didit AML Screening API

## Overview

Screens individuals or companies against 1,300+ global watchlists and high-risk databases in real-time. Uses a two-score system: **Match Score** (identity confidence) and **Risk Score** (threat level).

**Key constraints:**
- `full_name` is the only **required** field
- Supports `entity_type`: `"person"` (default) or `"company"`
- Document number acts as a "Golden Key" for definitive matching
- All weight parameters must sum to 100

**Coverage:** OFAC SDN, UN, EU, HM Treasury, Interpol, FBI, 170+ national sanction lists, PEP Levels 1-4, 50,000+ adverse media sources, financial crime databases.

**Scoring system:**
1. **Match Score** (0-100): Is this the same person? → classifies hits as False Positive or Unreviewed
2. **Risk Score** (0-100): How risky is this entity? → determines final AML status

**API Reference:** https://docs.didit.me/standalone-apis/aml-screening
**Feature Guide:** https://docs.didit.me/core-technology/aml-screening/overview
**Risk Scoring:** https://docs.didit.me/core-technology/aml-screening/aml-risk-score

---

## Authentication

All requests require `x-api-key` header. Get your key from [Didit Business Console](https://business.didit.me) → API & Webhooks, or via programmatic registration (see below).

## Getting Started (No Account Yet?)

If you don't have a Didit API key, create one in 2 API calls:

1. **Register:** `POST https://apx.didit.me/auth/v2/programmatic/register/` with `{"email": "you@gmail.com", "password": "MyStr0ng!Pass"}`
2. **Check email** for a 6-character OTP code
3. **Verify:** `POST https://apx.didit.me/auth/v2/programmatic/verify-email/` with `{"email": "you@gmail.com", "code": "A3K9F2"}` → response includes `api_key`

**To add credits:** `GET /v3/billing/balance/` to check, `POST /v3/billing/top-up/` with `{"amount_in_dollars": 50}` for a Stripe checkout link.

See the **didit-verification-management** skill for full platform management (workflows, sessions, users, billing).

---

## Endpoint

```
POST https://verification.didit.me/v3/aml/
```

### Headers

| Header | Value | Required |
|---|---|---|
| `x-api-key` | Your API key | **Yes** |
| `Content-Type` | `application/json` | **Yes** |

### Body (JSON)

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `full_name` | string | **Yes** | — | Full name of person or entity |
| `date_of_birth` | string | No | — | DOB in `YYYY-MM-DD` format |
| `nationality` | string | No | — | ISO country code (alpha-2 or alpha-3) |
| `document_number` | string | No | — | ID document number ("Golden Key") |
| `entity_type` | string | No | `"person"` | `"person"` or `"company"` |
| `aml_name_weight` | integer | No | `60` | Name weight in match score (0-100) |
| `aml_dob_weight` | integer | No | `25` | DOB weight in match score (0-100) |
| `aml_country_weight` | integer | No | `15` | Country weight in match score (0-100) |
| `aml_match_score_threshold` | integer | No | `93` | Below = False Positive, at/above = Unreviewed |
| `save_api_request` | boolean | No | `true` | Save in Business Console |
| `vendor_data` | string | No | — | Your identifier for session tracking |

### Example

```python
import requests

response = requests.post(
    "https://verification.didit.me/v3/aml/",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
        "full_name": "John Smith",
        "date_of_birth": "1985-03-15",
        "nationality": "US",
        "document_number": "AB1234567",
        "entity_type": "person",
    },
)
print(response.json())
```

```typescript
const response = await fetch("https://verification.didit.me/v3/aml/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    full_name: "John Smith",
    date_of_birth: "1985-03-15",
    nationality: "US",
  }),
});
```

### Response (200 OK)

```json
{
  "request_id": "a1b2c3d4-...",
  "aml": {
    "status": "Approved",
    "total_hits": 2,
    "score": 45.5,
    "hits": [
      {
        "id": "hit-uuid",
        "caption": "John Smith",
        "match_score": 85,
        "risk_score": 45.5,
        "review_status": "False Positive",
        "datasets": ["PEP"],
        "properties": {"name": ["John Smith"], "country": ["US"]},
        "score_breakdown": {
          "name_score": 95, "name_weight": 60,
          "dob_score": 100, "dob_weight": 25,
          "country_score": 100, "country_weight": 15
        },
        "risk_view": {
          "categories": {"score": 55, "risk_level": "High"},
          "countries": {"score": 23, "risk_level": "Low"},
          "crimes": {"score": 0, "risk_level": "Low"}
        }
      }
    ],
    "screened_data": {
      "full_name": "John Smith",
      "date_of_birth": "1985-03-15",
      "nationality": "US",
      "document_number": "AB1234567"
    },
    "warnings": []
  }
}
```

---

## Match Score System

**Formula:** `(Name × W1) + (DOB × W2) + (Country × W3)`

| Component | Default Weight | Algorithm |
|---|---|---|
| Name | 60% | RapidFuzz WRatio — handles typos, word order, middle name variations |
| DOB | 25% | Exact=100%, Year-only=100%, Same year diff date=50%, Mismatch=-100% |
| Country | 15% | Exact=100%, Mismatch=-50%, Missing=0%. Auto-converts ISO codes |

**Document Number "Golden Key":**

| Scenario | Effect |
|---|---|
| Same type, same value | Override score to **100** |
| Different type or one missing | Keep base score (neutral) |
| Same type, different value | **-50 point penalty** |

**Classification:** Score < threshold (default 93) → **False Positive**. Score >= threshold → **Unreviewed**.

> When data is missing, remaining weights are re-normalized. E.g., name-only → name weight becomes 100%.

---

## Risk Score System

**Formula:** `(Country × 0.30) + (Category × 0.50) + (Criminal × 0.20)`

**Final AML Status (from highest risk score among non-FP hits):**

| Highest Risk Score | Status |
|---|---|
| Below 80 (default) | **Approved** |
| Between 80-100 | **In Review** |
| Above 100 | **Declined** |
| All False Positives | **Approved** |

**Category scores (50% weight):**

| Category | Score |
|---|---|
| Sanctions / PEP Level 1 | 100 |
| Warnings & Regulatory | 95 |
| PEP Level 2 / Insolvency | 80 |
| Adverse Media | 60 |
| PEP Level 4 / Businessperson | 55 |

---

## Status Values & Handling

| Status | Meaning | Action |
|---|---|---|
| `"Approved"` | No significant matches or all False Positives | Safe to proceed |
| `"In Review"` | Matches found with moderate risk | Manual compliance review needed |
| `"Rejected"` | High-risk matches confirmed | Block or escalate per your policy |
| `"Not Started"` | Screening not yet performed | Check for missing data |

### Error Responses

| Code | Meaning | Action |
|---|---|---|
| `400` | Invalid request body | Check `full_name` and parameter formats |
| `401` | Invalid API key | Verify `x-api-key` header |
| `403` | Insufficient credits | Check credits in Business Console |

---

## Warning Tags

| Tag | Description |
|---|---|
| `POSSIBLE_MATCH_FOUND` | Potential watchlist matches requiring review |
| `COULD_NOT_PERFORM_AML_SCREENING` | Missing KYC data. Provide full name, DOB, nationality, document number |

---

## Response Field Reference

### Hit Object

| Field | Type | Description |
|---|---|---|
| `match_score` | integer | 0-100 identity confidence score |
| `risk_score` | float | 0-100 threat level score |
| `review_status` | string | `"False Positive"`, `"Unreviewed"`, `"Confirmed Match"`, `"Inconclusive"` |
| `datasets` | array | e.g. `["Sanctions"]`, `["PEP"]`, `["Adverse Media"]` |
| `pep_matches` | array | PEP match details |
| `sanction_matches` | array | Sanction match details |
| `adverse_media_matches` | array | `{headline, summa