didit-aml-screening

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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:

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

实时针对1300+全球观察名单和高风险数据库筛查个人或企业。采用双评分体系：匹配评分（Match Score）（身份置信度）和风险评分（Risk Score）（威胁等级）。

核心约束：

```
full_name
```
是唯一必填字段
支持
```
entity_type
```
：
```
"person"
```
（默认）或
```
"company"
```
文档编号作为“黄金密钥”用于确定性匹配
所有权重参数之和必须为100

覆盖范围： OFAC特别指定国民名单（SDN）、联合国、欧盟、英国财政部、国际刑警组织、联邦调查局、170+国家制裁名单、1-4级PEP、50000+负面媒体来源、金融犯罪数据库。

评分体系：

匹配评分（0-100）：是否为同一主体？→ 将命中结果分类为误报（False Positive）或待审核（Unreviewed）
风险评分（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

Authentication

身份验证

All requests require

x-api-key

header. Get your key from Didit Business Console → API & Webhooks, or via programmatic registration (see below).

所有请求均需携带

x-api-key

请求头。可从Didit企业控制台 → API与Webhooks获取密钥，或通过程序化注册获取（见下文）。

Getting Started (No Account Yet?)

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

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

Register:

POST https://apx.didit.me/auth/v2/programmatic/register/

with

{"email": "you@gmail.com", "password": "MyStr0ng!Pass"}

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

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

如果您还没有Didit API密钥，可通过2次API调用来创建：

注册： 发送

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/

请求，请求体为

{"amount_in_dollars": 50}

以获取Stripe结账链接。

如需完整平台管理（工作流、会话、用户、账单），请查看didit-verification-management技能。

Endpoint

接口端点

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

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

Headers

请求头

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

请求头	值	是否必填
`x-api-key`	您的API密钥	是
`Content-Type`	`application/json`	是

Body (JSON)

请求体（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

参数	类型	是否必填	默认值	说明
`full_name`	字符串	是	—	个人或企业的全名
`date_of_birth`	字符串	否	—	出生日期，格式为 `YYYY-MM-DD`
`nationality`	字符串	否	—	ISO国家代码（两位或三位字母）
`document_number`	字符串	否	—	身份证件编号（“黄金密钥”）
`entity_type`	字符串	否	`"person"`	`"person"` （个人）或 `"company"` （企业）
`aml_name_weight`	整数	否	`60`	匹配评分中姓名的权重（0-100）
`aml_dob_weight`	整数	否	`25`	匹配评分中出生日期的权重（0-100）
`aml_country_weight`	整数	否	`15`	匹配评分中国籍的权重（0-100）
`aml_match_score_threshold`	整数	否	`93`	低于该值=误报，等于/高于该值=待审核
`save_api_request`	布尔值	否	`true`	在企业控制台中保存请求记录
`vendor_data`	字符串	否	—	用于会话跟踪的自定义标识

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",
  }),
});

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)

响应结果（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": []
  }
}

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

计算公式：

(姓名 × W1) + (出生日期 × W2) + (国籍 × W3)

组成部分	默认权重	算法
姓名	60%	RapidFuzz WRatio — 处理拼写错误、词序颠倒、中间名变体等情况
出生日期	25%	完全匹配=100%，仅年份匹配=100%，同年不同日期=50%，不匹配=-100%
国籍	15%	完全匹配=100%，不匹配=-50%，未提供=0%。自动转换ISO代码

文档编号“黄金密钥”规则：

场景	影响
类型相同且值一致	强制将评分设为100
类型不同或其中一个未提供	保留基础评分（无影响）
类型相同但值不同	扣50分

分类规则： 评分 < 阈值（默认93）→ 误报（False Positive）。评分 ≥ 阈值 → 待审核（Unreviewed）。

若数据缺失，剩余权重将重新归一化。例如：仅提供姓名 → 姓名权重变为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

计算公式：

(国籍 × 0.30) + （类别 × 0.50） + （犯罪记录 × 0.20）

最终AML状态（基于所有非误报命中结果中的最高风险评分）：

最高风险评分	状态
低于80（默认）	通过（Approved）
80-100之间	审核中（In Review）
高于100	拒绝（Declined）
所有命中结果均为误报	通过（Approved）

类别评分（占50%权重）：

类别	评分
制裁名单 / 1级PEP	100
警告与监管名单	95
2级PEP / 破产名单	80
负面媒体	60
4级PEP / 企业高管	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

状态	含义	操作建议
`"Approved"`	无重大匹配结果或所有结果均为误报	可安全继续流程
`"In Review"`	发现中等风险匹配结果	需要人工合规审核
`"Rejected"`	确认存在高风险匹配结果	根据政策阻止或升级处理
`"Not Started"`	尚未执行筛查	检查是否存在数据缺失

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

状态码	含义	操作建议
`400`	请求体无效	检查 `full_name` 及参数格式
`401`	API密钥无效	验证 `x-api-key` 请求头
`403`	余额不足	在企业控制台中检查余额

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

标签	说明
`POSSIBLE_MATCH_FOUND`	发现潜在观察名单匹配结果，需要审核
`COULD_NOT_PERFORM_AML_SCREENING`	缺少KYC数据，请提供全名、出生日期、国籍、身份证件编号

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

字段	类型	说明
`match_score`	整数	0-100的身份置信度评分
`risk_score`	浮点数	0-100的威胁等级评分
`review_status`	字符串	`"False Positive"` , `"Unreviewed"` , `"Confirmed Match"` , `"Inconclusive"`
`datasets`	数组	例如 `["Sanctions"]` , `["PEP"]` , `["Adverse Media"]`
`pep_matches`	数组	PEP匹配详情
`sanction_matches`	数组	制裁名单匹配详情
`adverse_media_matches`	数组	`{headline, summary, source_url, sentiment_score, adverse_keywords}`
`linked_entities`	数组	关联个人/企业
`first_seen` / `last_seen`	字符串	ISO 8601格式时间戳

负面媒体情感值：

-1

= 轻微负面，

-2

= 中度负面，

-3

= 高度负面。

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

仅在**专业版（Pro plan）**中可用。所有AML筛查会话自动包含该功能。

每日自动重新筛查，同步最新观察名单
发现新的命中结果 → 根据阈值将会话状态更新为“审核中”或“拒绝”
状态变更实时Webhook通知
无需额外集成 — 使用工作流配置中的相同阈值

Common Workflows

常见工作流

Basic AML Check

基础AML检查

1. POST /v3/aml/ → {"full_name": "John Smith", "nationality": "US"}
2. If "Approved" → no significant watchlist matches
   If "In Review" → review hits[].datasets, hits[].risk_view for details
   If "Rejected" → block user, check hits for sanctions/PEP details

1. 发送POST /v3/aml/请求 → 请求体为{"full_name": "John Smith", "nationality": "US"}
2. 若状态为“Approved” → 无重大观察名单匹配结果
   若状态为“In Review” → 查看hits[].datasets、hits[].risk_view获取详情
   若状态为“Rejected” → 阻止用户，查看命中结果中的制裁/PEP详情

Comprehensive KYC + AML

全面KYC + AML检查

1. POST /v3/id-verification/ → extract name, DOB, nationality, document number
2. POST /v3/aml/ → screen extracted data with all fields populated
3. More data = higher match accuracy = fewer false positives

1. 发送POST /v3/id-verification/请求 → 提取姓名、出生日期、国籍、身份证件编号
2. 发送POST /v3/aml/请求 → 使用提取的所有字段进行筛查
3. 提供的数据越完整 → 匹配准确率越高 → 误报越少

Utility Scripts

实用脚本

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

bash

undefined

screen_aml.py：通过命令行针对AML观察名单进行筛查。

bash

undefined

Requires: pip install requests

依赖：pip install requests

export DIDIT_API_KEY="your_api_key" python scripts/screen_aml.py --name "John Smith" python scripts/screen_aml.py --name "John Smith" --dob 1985-03-15 --nationality US python scripts/screen_aml.py --name "Acme Corp" --entity-type company

undefined

undefined