管理 API v3：工作流与计费

认证

所有管理 API 端点都使用您的应用 API 密钥。URL 中无需包含组织或应用 UUID，系统会根据您的密钥识别应用。

curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/...

还没有 API 密钥？通过 2 次 API 调用以编程方式注册。

工作流

工作流定义了用户需要完成的验证步骤（证件扫描、活体检测、人脸比对、AML 筛查等）。每个工作流都是可复用的配置，您可以将其关联到会话。

GET

列出应用的所有工作流。返回每个工作流的功能、阈值以及是否为默认工作流。

POST

创建新的工作流。定义要启用的验证功能、设置阈值、配置可接受的证件类型等。

GET

获取指定工作流的完整详情，包括所有功能配置和阈值。

PATCH

更新工作流配置。您可以修改任意功能设置、阈值或可接受的证件。

DELETE

删除工作流。已使用该工作流的会话不受影响。

我们强烈建议您使用业务控制台创建和配置工作流。可视化工作流构建器提供模板、拖放式功能配置、证件设置、阈值调整和预览功能，无需编写代码即可完成。仅在需要自动化或以编程方式管理工作流时使用 API。

创建工作流示例

workflow_type 决定基础功能集。随后可通过 is_*_enabled 标志开启或关闭各项功能。

curl -X POST https://verification.didit.me/v3/workflows/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Standard KYC",
    "workflow_type": "kyc",
    "is_default": true,
    "is_face_match_enabled": true,
    "is_liveness_enabled": true,
    "is_aml_enabled": false
  }'

可用的 workflow_type 值：kyc、kyb、adaptive_age_verification、biometric_authentication、address_verification、questionnaire_verification、email_verification、phone_verification。对于 kyc 工作流，会自动包含证件验证，无需为其单独设置标志。使用 is_*_enabled 标志可添加或移除可选功能，例如人脸比对、活体检测、AML、NFC、电话、邮箱、地址证明、设备与 IP 分析等。然后在创建会话时使用该工作流：

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.com/callback",
    "workflow_id": "WORKFLOW_UUID_FROM_ABOVE"
  }'

问卷

您可以将自定义表单添加到验证工作流中，以收集用户的额外信息。

GET

列出所有问卷。

POST

创建新问卷，包含自定义问题、分支逻辑和翻译内容。

GET

获取问卷详情，包括所有问题和表单结构。

PATCH

更新问卷。

DELETE

删除问卷。

用户

管理应用中的已验证个人（用户）。每个用户由您在创建会话时提供的 vendor_data 字符串标识。

GET

列出应用的所有用户，包括其验证状态和会话历史。

GET

通过您的 vendor_data 标识符获取用户详情。

PATCH

更新用户元数据。

POST

批量删除用户。请求体：{"vendor_data_list": ["user-1", "user-2"]} 或 {"delete_all": true}。同时会清除为这些用户保留的所有生物特征模板。

生物特征模板

已选择加入的应用在删除会话后保留的不含图像的人脸生物特征模板。参见生物特征模板。

GET

分页列表，支持过滤条件（vendor_data、vendor_user_uuid、status、source_type、retained_from、retained_to、ordering）。

GET

使用相同过滤条件统计数量。

GET

获取单个模板：所属用户、来源引用、到期时间、指令和状态。

DELETE

清除单个模板。返回 {"uuid": "...", "outcome": "purged" | "already_purged"}。

POST

批量清除。请求体：{"template_uuids": [...]} 或 {"delete_all": true}，并可附加可选过滤条件。

会话操作

POST

批量删除会话。需要 delete:sessions 权限。请求体：{"session_numbers": ["1", "2", "3"]} 或 {"delete_all": true}（可使用以 filter_ 为前缀的会话列表过滤条件缩小 delete_all 的范围，例如 filter_status），并可附加可选参数 retain_face_embeddings、face_retention_days、face_retention_deadline、deletion_instruction 和 instruction_id。匹配的会话最多为 20 个时，返回 200，并附带每个会话的 face_retention_outcome；超过 20 个时，返回 202 和一个删除任务。

GET

查看返回 202 的批量会话删除任务的进度和结果计数。

GET

列出会话的审核记录和活动日志。

POST

为会话添加审核备注或状态变更。

计费

GET

获取当前额度余额和自动充值设置。

{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}

POST

创建 Stripe 结账会话以为额度充值。每次充值金额为 $50 至 $20,000，按面值计入。

{
  "amount_in_dollars": 100,
  "success_url": "https://myapp.com/billing/success",
  "cancel_url": "https://myapp.com/billing/cancel"
}

黑名单、白名单与自定义列表

按类型管理用于黑名单、白名单和自定义工作流条件的列表。完整内容请参阅列表 API 文档。

GET

列出应用的所有列表（黑名单、白名单、自定义）。

POST

向列表添加条目。支持使用 reference_session_id 从会话中自动提取数据，并支持使用 reference_object_uuid 追溯到交易、用户或企业。

DELETE

从列表中移除条目。

POST

向人脸黑名单上传人脸图片（base64）。

Webhook 配置

GET

获取当前 Webhook 配置，包括 URL、版本、用于验证 Webhook 签名的密钥，以及应用的数据保留策略和生物特征模板保留策略。响应中还包含 allowed_domains，说明见下文 PATCH /v3/webhook/。

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "secret_shared_key": "whsec_a1b2c3d4e5f6...",
  "capture_method": "both",
  "data_retention_months": null,
  "face_retention_policy": "delete_with_session",
  "face_retention_days": null,
  "allowed_return_hosts": ["app.example.com"],
  "allowed_domains": ["https://app.example.com"]
}

PATCH

更新 Webhook URL、版本或轮换密钥。设置 rotate_secret_key: true 可生成新的 Webhook 密钥，旧密钥会立即失效。同时设置应用的保留策略：data_retention_months，以及在启用保留时必须提供的 face_retention_policy（默认为 delete_with_session，或 retain_until_user_deleted）和有限值的 face_retention_days（1-3650）。详见生物特征模板保留。此外，还可注册 allowed_return_hosts：最多 20 个裸主机名（例如 app.example.com，不含协议、端口、路径或通配符），数字身份钱包 API 验证可通过 HTTPS 将用户返回这些主机。新列表会替换已注册的列表，您应用的白标域名始终被允许。此外，还可设置 allowed_domains：最多 50 个 Web 来源（例如 https://app.example.com），托管验证流程可嵌入这些来源，并可借助会话的 callback 将用户返回这些来源。每个条目由协议、主机和可选端口组成，不得包含路径、查询参数或通配符。请使用 https；仅 localhost、127.0.0.1 和 ::1 可以使用 http。 Didit 会将每个来源以小写形式存储，且不保留默认端口，并在 allowed_domains 中返回该列表。无效条目会在 allowed_domains 上返回 400 错误。新列表会替换已注册的列表，空列表会移除该限制。列表非空时，POST /v3/session/ 会拒绝列表之外的 Web callback，返回 400，托管流程也不会将用户重定向到列表之外的已存储或工作流默认回调地址。自定义 URL scheme（应用深层链接）和服务器到服务器的 API 调用不受影响。如果您发送 endpoints，列表中未包含的每个 Webhook 目标都会被永久删除，连同其签名密钥和完整投递日志一并删除，删除方式与 DELETE /v3/webhook/destinations/{destination_uuid}/ 完全相同。此操作无法撤销。如需逐个管理目标，请改用 Webhook 目标 endpoint。

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "allowed_domains": ["https://app.example.com"]
}

API endpoint 完整汇总

端点	方法	说明
`/v3/session/`	POST	创建验证会话
`/v3/sessions/`	GET	列出所有会话
`/v3/session/{id}/decision/`	GET	获取会话验证结果
`/v3/session/{id}/update-status/`	PATCH	批准或拒绝会话
`/v3/session/{id}/delete/`	DELETE	删除单个会话
`/v3/sessions/delete/`	POST	批量删除会话
`/v3/sessions/delete/{job_id}/`	GET	批量会话删除任务状态
`/v3/sessions/{id}/reviews/`	GET, POST	会话活动/审核记录
`/v3/workflows/`	GET, POST	列出/创建工作流
`/v3/workflows/{id}/`	GET, PATCH, DELETE	工作流详情/更新/删除
`/v3/questionnaires/`	GET, POST	列出/创建问卷
`/v3/questionnaires/{id}/`	GET, PATCH, DELETE	问卷详情
`/v3/users/`	GET	列出已验证用户
`/v3/users/{vendor_data}/`	GET, PATCH	用户详情/更新
`/v3/users/delete/`	POST	批量删除用户（同时清除其保留的生物特征模板）
`/v3/biometric-templates/`	GET	列出已保留的生物特征模板
`/v3/biometric-templates/count/`	GET	统计已保留的生物特征模板数量
`/v3/biometric-templates/{id}/`	GET, DELETE	模板详情/清除
`/v3/biometric-templates/delete/`	POST	批量清除模板
`/v3/lists/`	GET, POST	列出所有列表/创建列表
`/v3/lists/{id}/`	GET, PATCH, DELETE	列表详情/更新/删除
`/v3/lists/{id}/entries/`	GET, POST	列出条目/添加条目
`/v3/lists/{id}/entries/{eid}/`	DELETE	移除条目
`/v3/lists/{id}/entries/face-upload/`	POST	向黑名单上传人脸
`/v3/webhook/`	GET, PATCH	Webhook 配置（URL、密钥、版本）、保留策略和钱包返回主机
`/v3/billing/balance/`	GET	查询额度余额
`/v3/billing/top-up/`	POST	为额度充值

最后修改于 2026年11月7日

​认证

​工作流

​创建工作流示例

​问卷

​用户

​生物特征模板

​会话操作

​计费

​黑名单、白名单与自定义列表

​Webhook 配置

​API endpoint 完整汇总

认证

工作流

创建工作流示例

问卷

用户

生物特征模板

会话操作

计费

黑名单、白名单与自定义列表

Webhook 配置

API endpoint 完整汇总