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 INLINECODE3
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
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 → 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 INLINECODE6
Check email for a 6-character OTP code
Verify: POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with {"email": "you@gmail.com", "code": "A3K9F2"} → response includes INLINECODE9

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

CODEBLOCK0

Headers

Header	Value	Required
INLINECODE13	Your API key	Yes
INLINECODE14

application/json | Yes |

Body (JSON)

Parameter	Type	Required	Default	Description
INLINECODE16	string	Yes	—	Full name of person or entity
INLINECODE17

Example

CODEBLOCK1

CODEBLOCK2

Response (200 OK)

CODEBLOCK3

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

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: INLINECODE37

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

Highest Risk Score	Status
Below 80 (default)	Approved
Between 80-100

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
INLINECODE38	No significant matches or all False Positives	Safe to proceed
INLINECODE39

Error Responses

Code	Meaning	Action
INLINECODE42	Invalid request body	Check `full_name` and parameter formats
INLINECODE44

Warning Tags

Tag	Description
INLINECODE47	Potential watchlist matches requiring review
INLINECODE48

Missing KYC data. Provide full name, DOB, nationality, document number |

Response Field Reference

Hit Object

Field	Type	Description
INLINECODE49	integer	0-100 identity confidence score
INLINECODE50

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, summary, source_url, sentiment_score, adverse_keywords} | | linked_entities | array | Related persons/entities | | first_seen / last_seen | string | ISO 8601 timestamps |

Adverse media sentiment: -1 = slightly negative, -2 = moderately, -3 = highly negative.

Continuous Monitoring

Available on Pro plan. Automatically included for all AML-screened sessions.

- Daily automated re-screening against updated watchlists
New hits → session status updated to "In Review" or "Declined" based on thresholds
Real-time webhook notifications on status changes
Zero additional integration — uses same thresholds from workflow config

Common Workflows

Basic AML Check

CODEBLOCK4

Comprehensive KYC + AML

CODEBLOCK5

Utility Scripts

screen_aml.py: Screen against AML watchlists from the command line.

CODEBLOCK6

Didit AML 筛查 API

概述

实时将个人或公司与 1300+ 全球观察名单和高风险数据库进行比对。采用双评分系统：匹配分数（身份置信度）和风险分数（威胁等级）。

关键约束：

- fullname 是唯一必填字段
支持 entitytype：person（默认）或 company
证件号码作为确定性匹配的金钥匙
所有权重参数之和必须为 100

覆盖范围： OFAC SDN、联合国、欧盟、英国财政部、国际刑警组织、FBI、170+ 国家制裁名单、PEP 1-4 级、50,000+ 负面媒体来源、金融犯罪数据库。

评分系统：

1. 匹配分数（0-100）：是否为同一人？→ 将命中结果分类为误报或待审核
风险分数（0-100）：该实体风险有多高？→ 确定最终 AML 状态

API 参考： https://docs.didit.me/standalone-apis/aml-screening
功能指南： https://docs.didit.me/core-technology/aml-screening/overview
风险评分： https://docs.didit.me/core-technology/aml-screening/aml-risk-score

身份验证

所有请求都需要 x-api-key 标头。从 Didit 业务控制台 → API 和 Webhooks 获取您的密钥，或通过编程方式注册（见下文）。

快速入门（还没有账户？）

如果您没有 Didit API 密钥，通过 2 次 API 调用创建一个：

1. 注册： POST https://apx.didit.me/auth/v2/programmatic/register/ 附带 {email: you@gmail.com, password: MyStr0ng!Pass}
检查邮箱获取 6 位 OTP 验证码
验证： POST https://apx.didit.me/auth/v2/programmatic/verify-email/ 附带 {email: you@gmail.com, code: A3K9F2} → 响应包含 api_key

添加积分： GET /v3/billing/balance/ 查看余额，POST /v3/billing/top-up/ 附带 {amountindollars: 50} 获取 Stripe 结账链接。

有关完整的平台管理（工作流、会话、用户、计费），请参阅 didit-verification-management 技能。

端点

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

标头

标头	值	必填
x-api-key	您的 API 密钥	是
Content-Type

application/json | 是 |

请求体（JSON）

参数	类型	必填	默认值	描述
fullname	string	是	—	个人或实体的全名
dateof_birth

示例

python
import requests

response = requests.post(
https://verification.didit.me/v3/aml/,
headers={x-api-key: YOURAPIKEY, Content-Type: application/json},
json={
full_name: John Smith,
dateofbirth: 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: YOURAPIKEY, Content-Type: application/json },
body: JSON.stringify({
full_name: John Smith,
dateofbirth: 1985-03-15,
nationality: US,
}),
});

响应（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: {
namescore: 95, nameweight: 60,
dobscore: 100, dobweight: 25,
countryscore: 100, countryweight: 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,
dateofbirth: 1985-03-15,
nationality: US,
document_number: AB1234567
},
warnings: []
}
}

匹配分数系统

公式： (姓名 × W1) + (出生日期 × W2) + (国家 × W3)

组件	默认权重	算法
姓名	60%	RapidFuzz WRatio — 处理拼写错误、词序、中间名变体
出生日期

25% | 精确=100%，仅年份=100%，同年不同日期=50%，不匹配=-100% |
| 国家 | 15% | 精确=100%，不匹配=-50%，缺失=0%。自动转换 ISO 代码 |

证件号码金钥匙：

场景	效果
相同类型，相同值	覆盖分数为 100
不同类型或一个缺失

保留基础分数（中性） |
| 相同类型，不同值 | -50 分惩罚 |

分类： 分数 < 阈值（默认 93）→ 误报。分数 >= 阈值 → 待审核。

当数据缺失时，剩余权重会重新归一化。例如，仅姓名 → 姓名权重变为 100%。

风险分数系统

公式： (国家 × 0.30) + (类别 × 0.50) + (犯罪 × 0.20)

最终 AML 状态（基于非误报命中中的最高风险分数）：

最高风险分数	状态
低于 80（默认）	已批准
80-100 之间

审核中 |
| 高于 100 | 已拒绝 |
| 全部为误报 | 已批准 |

类别分数（50% 权重）：

类别	分数
制裁 / PEP 1 级	100
警告与监管

95 |
| PEP 2 级 / 破产 | 80 |
| 负面媒体 | 60 |
| PEP 4 级 / 商人 | 55 |

状态值及处理

状态	含义	操作
Approved	无显著匹配或全部为误报

didit-aml-screeningAML筛查