> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 名单 API：黑名单与白名单管理

> 通过 Didit 管理黑名单、白名单和自定义名单，用于 KYC、欺诈和交易筛查。Didit 是一站式身份基础设施，采用按次付费模式。



Lists API 提示词
        将提示词复制到剪贴板



      
      

\<pre>

\`Manage Didit blocklists, allowlists, and custom lists through the Management API.

Base path:
https://verification.didit.me/v3/lists/

Authentication:
Use the x-api-key header with my Didit API key on every call.

Concepts:
\- Blocklist — system-created, one per entry type. Items in a blocklist cause automatic decline during verification or transaction screening. Cannot be deleted or renamed.
\- Allowlist: created by you, or by Didit as a system allowlist that cannot be renamed or deleted. Used in workflow conditions and to suppress duplicate/reuse actions for trusted matching items.
\- Custom — user-created. Flexible lists for workflow branching, monitoring rules, or manual review.

Supported entry_type values:
face, document, phone, email, ip_address, device_fingerprint, wallet_address, bank_account, user, business, country, key.

Endpoints I should know:
\- GET /v3/lists/ — list all lists (filter by list_type, entry_type).
\- POST /v3/lists/ — create allowlist or custom list (cannot create blocklists).
\- GET /v3/lists/{list_uuid}/ — get one list.
\- PATCH /v3/lists/{list_uuid}/ — rename or update description (system lists immutable).
\- DELETE /v3/lists/{list_uuid}/ — delete allowlist/custom only. Returns 204.
\- GET /v3/lists/{list_uuid}/entries/ — paginated entries; supports search query.
\- POST /v3/lists/{list_uuid}/entries/ — add an entry by value, by reference_session_id, or by reference_object_uuid + metadata.reference_type ("transaction" | "vendor_user" | "vendor_business").
\- POST /v3/lists/{list_uuid}/entries/face-upload/: upload a base64 face image to a face blocklist or face allowlist; Didit extracts the biometric.
\- DELETE /v3/lists/{list_uuid}/entries/{entry_uuid}/ — remove an entry. For system blocklists this auto-unblocks the underlying entity.

Value validation (Create entry):
\- email — valid email address.
\- phone — valid international phone number (auto-normalized to E.164).
\- ip_address — IP or CIDR range (e.g. 10.0.0.0/8).
\- device_fingerprint: at least 8 characters among letters, digits, -, _, : and . (a blocklist refuses a fingerprint that several distinct devices have reported).
\- country — ISO 3166-1 alpha-3 (alpha-2 is accepted and converted).
\- Other types — any non-empty string. Values are case-insensitive and normalized on storage.

Traceability:
\- Pass reference_session_id when blocklisting from a verification session: Didit auto-extracts the right value (face/document/phone/email/IP/device), marks the underlying model as blocklisted, and links the entry back to the session. Didit reads the session's most recent record of that type; to list a value from an earlier record, add it by value without reference_session_id.
\- Pass reference_object_uuid plus metadata.reference_type ("transaction" | "vendor_user" | "vendor_business") when blocklisting from a transaction or vendor user/business so the console can link back to the source.

Common failure modes:
\- 400: value fails the entry_type validator or is already in the list, list_type is wrong for the operation (e.g. POST face-upload on a non-face list), reference_session_id has no data of the requested type, a system list is modified or deleted, or a list name is already used in this application (on create or rename).
\- 401: the API key has expired.
\- 403: missing x-api-key (a wrong, revoked or expired key gets 401) ({ "detail": "You do not have permission to perform this action." }), or a scoped key without workflows access.
\- 404: list or entry not found in this application (a list of another application also returns 404).

Side effects:
\- Adding to a system blocklist immediately blocks future matches at verification/screening time.
\- Deleting an entry from a system blocklist unblocks the matching entity.
\- Lists are referenced by workflow status_rules (value_type: "list") for runtime list checks.

For the full integration shape (auth, retries, error handling), see /integration/integration-prompt.`

\</pre>



      
      

粘贴到

Lists API 可让您管理应用中不同类型的名单。系统黑名单会在验证和交易筛查期间自动创建并进行检查。您还可以创建白名单和自定义名单，用于工作流条件。## 概念| 类型 | 描述 |
| - | - |
| **黑名单** | 由系统创建，每种条目类型一个。黑名单中的项目会在验证或交易筛查期间自动导致拒绝。 |
| **白名单** | 由用户创建。用于工作流条件，并可抑制可信匹配项的重复/复用操作。 |
| **自定义** | 由用户创建。灵活的名单，可用于工作流分支、监控规则或人工审核。 |## 条目类型| 条目类型 | 检查时机 | 命中后 |
| - | - | - |
| `face` | 活体检测 | 会话已拒绝 |
| `document` | 身份证件验证（OCR） | 会话已拒绝 |
| `phone` | 电话验证 | 会话已拒绝 |
| `email` | 邮箱验证 | 会话已拒绝 |
| `ip_address` | 设备与 IP 分析（支持 CIDR 范围） | 会话已拒绝 |
| `device_fingerprint` | 设备与 IP 分析 | 会话已拒绝 |
| `wallet_address` | 交易筛查 | 交易已拒绝 |
| `bank_account` | 交易筛查 | 交易已拒绝 |
| `user` | 交易筛查 | 用户已被拦截 |
| `business` | 交易筛查 | 企业已被拦截 |
| `country` | 工作流条件 | 可配置 |
| `key` | 自定义用途 | 可配置 |## 白名单白名单不会覆盖黑名单或真实性检查。白名单只会抑制同一条目类型的重复/复用操作。例如，人脸白名单中的人脸可以跳过 `DUPLICATED_FACE` 操作，IP 白名单中的 IP 可以跳过 `DUPLICATED_IP_ADDRESS` 操作，设备指纹白名单中的设备指纹可以跳过 `DUPLICATED_DEVICE_FINGERPRINT` 操作。Didit 仍会记录一条提示性的白名单警告，方便您审计重复操作未执行的原因。## 系统黑名单每个应用都会自动获得 10 个系统黑名单（每种受支持的条目类型一个）以及一个系统 **高风险国家/地区** 名单。这些名单不能删除或重命名。您可以通过 API 或控制台向其中添加条目。## 可追溯性每个黑名单条目都可以链接回其来源实体，以便您从名单跳转到原始记录：- **从会话**：创建条目时传入 `reference_session_id`（参见[创建条目](https://docs.didit.me/zh/management-api/lists/create-entry.md)）。Didit 会自动提取该值（人脸、证件、电话、邮箱、IP 或设备），将底层模型标记为已加入黑名单，并将条目链接回该会话。Didit 会读取该会话中该类型的最新记录；若要添加较早记录中的值，请仅通过 `value` 添加，不传入 `reference_session_id`。
- **从交易、用户或企业**：传入实体的 UUID 作为 `reference_object_uuid`，并包含 `metadata.reference_type`（`"transaction"`、`"vendor_user"` 或 `"vendor_business"`），以便控制台链接回原始记录。## Endpoints> [card] [列出所有名单](https://docs.didit.me/zh/management-api/lists/list.md)
>
> 获取应用的所有名单。> [card] [名单条目](https://docs.didit.me/zh/management-api/lists/list-entries.md)
>
> 获取名单中的条目。> [card] [创建条目](https://docs.didit.me/zh/management-api/lists/create-entry.md)
>
> 向黑名单添加一个值，可通过值、会话引用或交易引用添加。> [card] [删除条目](https://docs.didit.me/zh/management-api/lists/delete-entry.md)
>
> 删除条目并解除对底层实体的拦截。> [card] [上传人脸](https://docs.didit.me/zh/management-api/lists/upload-face.md)
>
> 直接将人脸图像上传到人脸黑名单。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.