Running KYC with Didit
End-to-end Know Your Customer (KYC) verification. This skill creates a KYC workflow, generates a session URL where a real user completes ID scan + selfie + face match, and retrieves the verification decision.
What the user experiences:
- 1. Receives a verification link
- Scans their ID document (passport, ID card, driver's license)
- Takes a live selfie
- System auto-matches selfie to document photo
- Gets approved, declined, or flagged for review
API Reference:
- - Workflows: https://docs.didit.me/management-api/workflows/create
- Sessions: https://docs.didit.me/sessions-api/create-session
- Decisions: https://docs.didit.me/sessions-api/retrieve-session
- Programmatic Registration: https://docs.didit.me/integration/programmatic-registration
- Full API Overview: https://docs.didit.me/sessions-api/management-api
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 INLINECODE2 - 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 INLINECODE5
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).
Quick Start — KYC in 3 API Calls
CODEBLOCK0
Step 1: Create a KYC Workflow
A workflow defines what checks run. Create one per use case and reuse it for all users.
CODEBLOCK1
API Reference: https://docs.didit.me/management-api/workflows/create
Recommended KYC Configuration
| Parameter | Value | Why |
|---|
| INLINECODE9 | INLINECODE10 | Full KYC template with ID + selfie |
| INLINECODE11 |
true | Prevents spoofing (printed photos, screens) |
|
is_face_match_enabled |
true | Compares selfie to document photo |
|
face_match_score_decline_threshold |
50 | Match below 50% → auto-decline |
|
is_aml_enabled |
false | Set
true for sanctions/PEP screening (+cost) |
|
max_retry_attempts |
3 | User can retry 3 times on failure |
Response
CODEBLOCK2
Save uuid as your workflow_id.
Step 2: Create a Session for Each User
Each user gets their own session. The session generates a unique URL where they complete verification.
CODEBLOCK3
API Reference: https://docs.didit.me/sessions-api/create-session
Key Parameters
| Parameter | Type | Required | Description |
|---|
| INLINECODE24 | uuid | Yes | From Step 1 |
| INLINECODE25 |
string | Recommended | Your user ID — links the session to your system |
|
callback | url | Recommended | Redirect URL after verification. Didit appends
?verificationSessionId=...&status=... |
|
language | string | No | UI language (ISO 639-1). Auto-detected if omitted |
|
contact_details.email | string | No | Pre-fill email for notification |
|
expected_details.first_name | string | No | Triggers mismatch warning if document name differs |
|
expected_details.date_of_birth | string | No |
YYYY-MM-DD format |
|
metadata | JSON string | No | Custom data stored with session |
Response
CODEBLOCK4
Send the user to url — this is where they complete verification (web or mobile).
Step 3: Get the Decision
After the user completes verification, retrieve the results.
CODEBLOCK5
API Reference: https://docs.didit.me/sessions-api/retrieve-session
Two Ways to Know When It's Ready
Option A: Webhooks (recommended for production)
Configure a webhook URL in Business Console → API & Webhooks. Didit sends a POST with session_id and status when the decision is ready.
Option B: Polling
Poll GET /v3/session/{id}/decision/ every 10–30 seconds. Check status — stop when it's Approved, Declined, or In Review.
Decision Response Fields
CODEBLOCK6
Key Decision Statuses
| Status | Meaning | Action |
|---|
| INLINECODE42 | All checks passed | User is verified |
| INLINECODE43 |
One or more checks failed | Check
warnings for details |
|
In Review | Borderline result | Manual review needed, or auto-decide via API |
|
Not Started | User hasn't opened the link yet | Wait or remind user |
|
In Progress | User is completing verification | Wait |
|
Expired | Session expired (default: 7 days) | Create a new session |
Optional: Post-Decision Actions
Approve or Decline Manually
CODEBLOCK7
API Reference: https://docs.didit.me/sessions-api/update-status
CODEBLOCK8
Request Resubmission
If the ID photo was blurry, ask the user to redo just that step:
CODEBLOCK9
Block Fraudulent Users
CODEBLOCK10
API Reference: https://docs.didit.me/sessions-api/blocklist/add
Generate PDF Report
CODEBLOCK11
API Reference: https://docs.didit.me/sessions-api/generate-pdf
KYC Workflow Variants
KYC + AML Screening
Add sanctions/PEP screening to catch high-risk individuals:
CODEBLOCK12
KYC + Phone + Email
Add contact verification to the flow:
CODEBLOCK13
KYC + NFC (Chip Reading)
For passports with NFC chips — highest assurance:
CODEBLOCK14
Utility Scripts
run_kyc.py — Full KYC setup from the command line
CODEBLOCK15
Can also be imported:
CODEBLOCK16
使用Didit进行KYC验证
端到端客户身份验证（KYC）。此技能创建KYC工作流程，生成一个会话URL，真实用户在该URL上完成身份证扫描+自拍+人脸匹配，并获取验证结果。
用户体验流程：
- 1. 收到验证链接
- 扫描身份证件（护照、身份证、驾照）
- 拍摄实时自拍照
- 系统自动将自拍照与证件照片进行匹配
- 获得通过、拒绝或标记待审核的结果
API参考：
- - 工作流程：https://docs.didit.me/management-api/workflows/create
- 会话：https://docs.didit.me/sessions-api/create-session
- 结果：https://docs.didit.me/sessions-api/retrieve-session
- 程序化注册：https://docs.didit.me/integration/programmatic-registration
- 完整API概览：https://docs.didit.me/sessions-api/management-api
身份验证
所有请求都需要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技能。
快速开始 — 3次API调用完成KYC
python
import requests, time
APIKEY = yourapi_key
headers = {x-api-key: API_KEY, Content-Type: application/json}
BASE = https://verification.didit.me/v3
1. 创建KYC工作流程（一次性设置 — 对所有用户复用workflow_id）
workflow = requests.post(f{BASE}/workflows/, headers=headers, json={
workflow_label: KYC Onboarding,
workflow_type: kyc,
is
livenessenabled: True,
is
facematch_enabled: True,
face
matchscore
declinethreshold: 50,
max
retryattempts: 3,
}).json()
workflow_id = workflow[uuid]
2. 为特定用户创建会话
session = requests.post(f{BASE}/session/, headers=headers, json={
workflow
id: workflowid,
vendor_data: user-abc-123,
callback: https://yourapp.com/verification-done,
language: en,
}).json()
print(f将用户发送至：{session[url]})
用户打开此URL → 扫描身份证 → 拍摄自拍照 → 完成
3. 轮询获取结果（或使用webhooks）
while True:
decision = requests.get(
f{BASE}/session/{session[session_id]}/decision/,
headers={x-api-key: API_KEY},
).json()
status = decision[status]
if status in (Approved, Declined, In Review):
break
time.sleep(10)
print(f结果：{status})
if status == Approved:
iddata = decision[idverifications][0]
print(f姓名：{iddata[firstname]} {iddata[lastname]})
print(f出生日期：{iddata[dateof_birth]})
print(f证件类型：{iddata[documenttype]} ({iddata[issuingcountry]}))
步骤1：创建KYC工作流程
工作流程定义了要运行的检查项。为每个用例创建一个，并对所有用户复用。
POST https://verification.didit.me/v3/workflows/
API参考： https://docs.didit.me/management-api/workflows/create
推荐的KYC配置
| 参数 | 值 | 原因 |
|---|
| workflowtype | kyc | 完整的KYC模板，包含身份证+自拍照 |
| isliveness_enabled |
true | 防止欺诈（打印照片、屏幕） |
| is
facematch_enabled | true | 将自拍照与证件照片进行比对 |
| face
matchscore
declinethreshold | 50 | 匹配度低于50%→自动拒绝 |
| is
amlenabled | false | 设置为true进行制裁/PEP筛查（增加费用） |
| max
retryattempts | 3 | 用户失败后可重试3次 |
响应
json
{
uuid: d8d2fa2d-c69c-471c-b7bc-bc71512b43ef,
workflow_label: KYC Onboarding,
workflow_type: kyc,
features: [ocr, liveness, face_match],
total_price: 0.10,
workflow_url: https://verify.didit.me/...
}
保存uuid作为您的workflow_id。
步骤2：为每个用户创建会话
每个用户都有自己的会话。会话生成一个唯一的URL，用户在该URL上完成验证。
POST https://verification.didit.me/v3/session/
API参考： https://docs.didit.me/sessions-api/create-session
关键参数
| 参数 | 类型 | 必填 | 描述 |
|---|
| workflowid | uuid | 是 | 来自步骤1 |
| vendordata |
string | 推荐 | 您的用户ID — 将会话链接到您的系统 |
| callback | url | 推荐 | 验证后的重定向URL。Didit会附加?verificationSessionId=...&status=... |
| language | string | 否 | UI语言（ISO 639-1）。省略时自动检测 |
| contact_details.email | string | 否 | 预填邮箱用于通知 |
| expected
details.firstname | string | 否 | 如果证件姓名不同，触发不匹配警告 |
| expected
details.dateof_birth | string | 否 | YYYY-MM-DD格式 |
| metadata | JSON字符串 | 否 | 与会话一起存储的自定义数据 |
响应
json
{
session_id: 11111111-2222-3333-4444-555555555555,
session_token: abcdef123456,
url: https://verify.didit.me/session/abcdef123456,
status: Not Started,
workflow_id: d8d2fa2d-...
}
将用户发送至url — 这是他们完成验证的地方（网页或移动端）。
步骤3：获取结果
用户完成验证后，检索结果。
GET https://verification.didit.me/v3/session/{sessionId}/decision/
API参考： https://docs.didit.me/sessions-api/retrieve-session
两种知晓结果就绪的方式
选项A：Webhooks（推荐用于生产环境）
在业务控制台→ API和Webhooks中配置webhook URL。当结果就绪时，Didit会发送包含sessionid和status的POST请求。
选项B：轮询
每10-30秒轮询GET /v3/session/{id}/decision/。检查status — 当状态为Approved、Declined或In Review时停止。
结果响应字段
json
{
session_id: ...,
status: Approved,
features: [IDVERIFICATION, LIVENESS, FACEMATCH],
id_verifications: [{
status: Approved,
document_type: PASSPORT,
issuing_country: USA,
first_name: John,
last_name: Doe,
dateofbirth: 1990-01-15
