> ## 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 将人脸、证件、IP 地址、钱包地址、邮箱或电话条目添加到黑名单、白名单或自定义名单，以编程方式实现合规与欺诈防控。 创建名单条目 API 提示词 将提示词复制到剪贴板 \

\`Add an entry to a Didit list (blocklist, allowlist, or custom) through the Management API.

Endpoint:
POST https://verification.didit.me/v3/lists/{list_uuid}/entries/

Authentication:
Use the x-api-key header with my Didit API key. A scoped API key needs workflows: write.

Goal:
\- Insert a single entry into a list. Three add modes are supported:
1\. By value: pass value matching the list's entry_type.
2\. From a verification session: pass reference_session_id and Didit reads the value from the session's most recent record of the list's entry_type (face, document, phone, email, ip_address, device_fingerprint) and links the entry to the session.
3\. With a source reference: pass value plus reference_object_uuid and metadata.reference_type so the console links the entry back to the transaction, user or business it came from.

Path parameter:
\- list_uuid: list UUID from GET /v3/lists/. For a face without a session, use POST /v3/lists/{list_uuid}/entries/face-upload/ instead.

Request body (application/json):
\{
"value": "string",                  // required unless reference_session_id is sent
"reference_session_id": "uuid",     // optional: read the value from this session of my application
"reference_object_uuid": "uuid",    // optional: transaction UUID, or didit_internal_id of a user or business
"face_image_source": "liveness" | "front_image_camera_front" | "back_image_camera_front", // optional, system face blocklist + reference_session_id only; default liveness
"reference_node_id": "string",      // optional, with a document-capture face_image_source: which ID verification node's selfie to use
"display_label": "string",          // optional, at most 512 characters
"comment": "string",                // optional, reason or note
"metadata": {                       // optional, free-form; reference_image_url and front_image_url are ignored
"reference_type": "transaction" | "vendor_user" | "vendor_business",
"reference_id": "uuid"
}
}

Value validation by entry_type:
\- email: valid email address.
\- phone: valid international phone number (stored in E.164).
\- ip_address: IP address 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-2 or alpha-3 (stored as alpha-3).
\- user, business: the vendor_data to block.
\- face, document, wallet_address, bank_account, key: any non-empty string.
Values are case-insensitive: country codes are stored in upper case, phone numbers in E.164, everything else in lower case.
A list holds each value once: adding a value that is already there returns 400.

Adding from a session, what Didit does:
\- Looks up the session (it must belong to the same application).
\- Reads the value from the session's most recent record of the list's entry_type:
\- face: the liveness face (value is the face UUID). With face_image_source = front_image_camera_front / back_image_camera_front, the face from the selfie the front camera took while the user photographed the front / back of their document instead (system face blocklist only, leave value empty).
\- document: the document number; full_name, issuing_state, document_type, region and document_number go into metadata.
\- phone / email: the phone number / email address.
\- ip_address: the session's IP address.
\- device_fingerprint: a fingerprint that identifies one device. On a blocklist, Didit refuses a session that only has a device-class fingerprint or was completed on more than one device; pass the exact fingerprint as value in that case.
\- Links the entry to the session (reference_session_id) and to that record (reference_object_uuid).
\- If I also send value, Didit stores my value but still links the most recent record. To list a value from an earlier record, add it by value without reference_session_id.

Example calls:
\# By value
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"value": "+14155552671", "comment": "Reported fraud"}'

\# From a session
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"reference_session_id": "33333333-4444-5555-6666-777777777777"}'

\# The face from the selfie taken during document capture (system face blocklist)
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"reference_session_id": "33333333-4444-5555-6666-777777777777", "face_image_source": "front_image_camera_front"}'

\# From a transaction
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"value": "0x52908400098527886E0F7030069857D2E4169EE7", "reference_object_uuid": "55555555-6666-7777-8888-999999999999", "metadata": {"reference_type": "transaction"}}'

Failure modes:
\- 400: value fails the entry_type validator or is already in the list, neither value nor reference_session_id was sent, reference_session_id is not a session of this application, or the session has no data of the list's entry_type.
\- 400 (face_image_source): the list is not the system face blocklist, value was sent, the session has no image for that source, no clear face was found in that selfie, or that selfie is already in the blocklist.
\- 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: write.
\- 404: list not found in this application ({ "detail": "List not found." }).
\- 503 (face_image_source): face analysis is temporarily unavailable; nothing was added, retry later.
\- 429: rate limited (see /integration/rate-limiting); back off and retry.

Side effects:
\- System face, document, phone and email blocklists: a record read from a session is flagged as blocklisted at once, and new sessions that match it are declined.
\- System user and business blocklists: users or businesses of the application whose vendor_data equals value (or whose UUID equals reference_object_uuid) are set to BLOCKED.
\- Sessions and transactions that already finished are not changed.

For the full integration shape, see /integration/integration-prompt.`

\
粘贴到 向名单中添加一个条目。该值会根据名单的条目类型进行验证：* **邮箱**：有效的电子邮件地址 * **电话**：有效的国际电话号码，以 E.164 格式存储（例如 `+14155552671`） * **ip\_address**：有效的 IP 地址或 CIDR 范围（例如 `192.168.1.1` 或 `10.0.0.0/8`） * **device\_fingerprint**：至少 8 个字符，由字母、数字以及 `-`、`_`、`:` 和 `.` 组成。黑名单会拒绝被多台不同设备上报过的指纹，因为屏蔽该指纹会误拒无关的人。 * **国家/地区**：有效的 [ISO 3166-1 alpha-3 国家/地区代码](https://docs.didit.me/zh/core-technology/id-verification/supported-documents-id-verification.md)（例如 `USA`、`GBR`、`ESP`）。接受 alpha-2 代码（例如 `US`），并会自动转换为 alpha-3。 * **用户**、**企业**：用户或企业的 `vendor_data` * **人脸**、**证件**、**wallet\_address**、**bank\_account**、**密钥**：任何非空字符串> [!NOTE] > > 所有条目值都**不区分大小写**。您发送的值会在存储时规范化（电话号码转为 E.164 格式，国家/地区代码转为大写，其他内容转为小写），并在验证时不区分大小写地进行匹配。例如，屏蔽 `User@Example.COM` 也会拦截 `user@example.com`。名单中每个值只保存一次，添加名单中已存在的值会返回 `400`。对于人脸，如果您只有图片，请使用[上传人脸](https://docs.didit.me/zh/management-api/lists/upload-face.md)；如果要获取现有会话中的人脸，请发送 `reference_session_id`。人脸条目需要已存储的人脸用于比对，而手动输入的 `value` 无法提供这一点。## 从会话添加提供 `reference_session_id` 时，Didit 会执行以下操作：1) 查找该会话（会话必须属于同一应用） 2) 从会话中该名单条目类型的**最近**一条记录读取值： * **人脸**：活体检测自拍照中的人脸；`value` 为人脸 UUID * **证件**：证件号码；姓名、签发地、证件类型、地区和证件号码存储在 `metadata` 中，`display_label` 默认为持有人的姓名和证件号码 * **电话**：电话号码 * **邮箱**：电子邮件地址 * **ip\_address**：会话的 IP 地址 * **device\_fingerprint**：能够标识单一设备的指纹，优先选择完成过验证步骤的设备。在黑名单上，如果会话只包含设备类指纹，或会话是在多台设备上完成的，Didit 会拒绝该会话：此时请将精确的指纹作为 `value` 发送。 3) 将条目关联到会话（`reference_session_id`）和记录（`reference_object_uuid`），以便追溯在系统的人脸、证件、电话和邮箱黑名单中，该记录还会被标记为已列入黑名单，因此匹配它的新会话会被拒绝。对于其他条目类型，请同时发送 `value`。如果未找到会话，或会话中不包含所请求条目类型的数据，则返回 `400`。### 来自证件拍摄自拍照的人脸用户拍摄证件时，前置摄像头可以为其拍摄自拍照（即[身份证件验证报告](https://docs.didit.me/zh/core-technology/id-verification/report-id-verification.md)中的 `front_image_camera_front` 和 `back_image_camera_front` 图片）。该人脸除了可以作为活体检测人脸外，也可以添加到人脸黑名单中：传入 `face_image_source` 并指定所需的图片。```json theme={null} { "reference_session_id": "33333333-4444-5555-6666-777777777777", "face_image_source": "front_image_camera_front" } ```- 条目仅创建在系统**人脸黑名单**中，必须将 `value` 留空：Didit 会从会话的自拍照中获取人脸。 - 自拍照必须包含一张清晰的人脸。否则请求返回 `400`，且不会添加任何内容。 - 每张自拍照只能添加一次。条目的 `metadata.face_image_source` 和 `metadata.reference_node_id` 会说明其来源的自拍照。 - 在包含多个身份证件验证步骤的工作流中，`reference_node_id` 用于选择使用哪个步骤的自拍照。默认情况下，Didit 使用包含该自拍照的最近一次身份证件验证。 - 此后，该人脸会像其他黑名单人脸一样被检查：与每个新会话的活体检测自拍照比对，并与每个新的证件拍摄自拍照比对（参见 [`FRONT_CAMERA_FACE_IN_BLOCKLIST`](https://docs.didit.me/zh/core-technology/id-verification/warnings-id-verification)）。 - 删除该条目会将人脸移出黑名单，之后它将不再匹配新会话。### 同一会话中包含多条同类型记录一个会话可以包含同一类型的多条记录，例如多步骤工作流中的两个电话号码。Didit 始终读取**最近的**一条。如果同时发送 `value` 和 `reference_session_id`，条目会存储您的 `value`，但仍关联到该最近的记录；在系统黑名单上，被标记的也是该记录。如需列入较早记录中的值，请仅通过 `value` 添加，不要传入 `reference_session_id`：```json theme={null} { "value": "+34612345678", "comment": "First phone number of session 42" } ```## 引用交易、用户和企业将交易或服务商用户/企业的数据加入黑名单时，请将实体的 UUID 作为 `reference_object_uuid` 传入，并在 `metadata` 中注明来源类型：```json theme={null} { "value": "0x52908400098527886E0F7030069857D2E4169EE7", "reference_object_uuid": "55555555-6666-7777-8888-999999999999", "metadata": { "reference_type": "transaction", "reference_id": "55555555-6666-7777-8888-999999999999" } } ```这样您可以在控制台中从黑名单条目返回原始交易、用户或企业。Didit 会存储您的 `metadata` 键，但 `reference_image_url` 和 `front_image_url` 除外，这两个键只能由 Didit 设置。对于从会话中读取的条目，Didit 会在您的键之外添加其自有的键，且 Didit 的键优先。| 来源实体 | `reference_object_uuid` | `metadata.reference_type` | | - | - | - | | 验证会话 | 由 Didit 设置（人脸、证件、电话或邮箱记录） | 无需设置：请使用 `reference_session_id` | | 交易 | 交易 UUID | `"transaction"` | | 服务商用户 | `didit_internal_id` | `"vendor_user"` | | 服务商企业 | `didit_internal_id` | `"vendor_business"` |在系统的**用户**和**企业**黑名单上，Didit 还会将匹配的用户或企业设置为 `BLOCKED`：即 `vendor_data` 等于 `value` 的用户或企业，或 `didit_internal_id` 等于 `reference_object_uuid` 的用户或企业。请参见[用户黑名单](https://docs.didit.me/zh/entities/users/blocklist.md)和[企业黑名单](https://docs.didit.me/zh/entities/businesses/blocklist.md)。 ## OpenAPI ````yaml zh/openapi-25.json POST /v3/lists/{list_uuid}/entries/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/lists/{list_uuid}/entries/: post: tags: - Lists summary: 创建列表条目 description: >- 通过以下三种方式之一向名单添加一个条目：通过 `value` 添加；通过带有 `reference_session_id` 的验证会话添加，此时 Didit 会从该会话中读取该名单条目类型的最新记录并将条目与其关联；或通过带有 `reference_object_uuid` 和 `metadata.reference_type` 的 `value` 添加，指向交易、用户或企业。在系统人脸、证件、电话和邮箱黑名单上，从会话中读取的记录也会被标记为列入黑名单，因此新的匹配会话将被拒绝；在系统用户和企业黑名单上，匹配的用户或企业将被设置为 `BLOCKED`。已完成的会话和交易不会被修改。限定范围的 API 密钥需要具备 `workflows: write` 权限。各模式详情请参阅[创建名单条目](https://docs.didit.me/zh/management-api/lists/create-entry)。 operationId: create_list_entry parameters: - name: list_uuid in: path required: true description: 要添加到的列表的 UUID。对于您只有图像的人脸，请改用上传人脸至列表。 schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 requestBody: required: true content: application/json: schema: type: object description: 发送 `value`、`reference_session_id` 或两者。适用哪些字段取决于名单的 `entry_type`。 properties: value: type: string description: >- 要列出的值，根据列表的 `entry_type` 进行验证：`email` 为有效的邮箱地址；`phone` 为有效的国际号码，以 E.164 格式存储；`ip_address` 为 IP 地址或 CIDR 范围（例如 `10.0.0.0/8`）；`device_fingerprint` 为字母、数字、`-`、`_`、`:` 和 `.` 组成的至少 8 个字符（黑名单会拒绝多个不同设备报告过的指纹）；`country` 为 ISO 3166-1 alpha-2 或 alpha-3 代码，以 alpha-3 格式存储；`user` 和 `business` 为 `vendor_data`；任何其他类型为非空字符串。除电话号码和国家/地区代码外均以小写形式存储，列表对每个值只保存一次（不区分大小写）。除非发送了 `reference_session_id`，否则为必填项；当 `face_image_source` 为证件采集时必须留空。 reference_session_id: type: string format: uuid description: >- 从您应用的个人验证或企业验证会话中提取值。Didit 读取该会话中名单条目类型（`face`、`document`、`phone`、`email`、`ip_address` 或 `device_fingerprint`）的最新记录，将条目链接到该会话和该记录，并为证件填充 `display_label` 和 `metadata`。对于 `device_fingerprint` 黑名单，仅包含设备类别指纹或在多台设备上完成的会话会被拒绝：请将精确指纹作为 `value` 发送。对于其他条目类型，或当会话没有此类记录时，也请发送 `value`；随后将存储您的 `value`，且条目仍会链接到该会话。 reference_object_uuid: type: string format: uuid description: >- 当条目并非来自会话时，其所代表记录的 UUID：交易 UUID，或用户或企业的 `didit_internal_id`。与 `metadata.reference_type` 配合使用。当 `reference_session_id` 提供了记录时，将被会话的记录替换。 face_image_source: type: string enum: - liveness - front_image_camera_front - back_image_camera_front default: liveness description: >- 带有 `reference_session_id` 的人脸名单：人脸取自该会话的哪张图像。`liveness`（默认值）为活体自拍照。`front_image_camera_front` 和 `back_image_camera_front` 是用户拍摄证件正面或背面时前置摄像头拍摄的自拍照：仅在系统人脸黑名单上被接受，且需带有 `reference_session_id` 以及空的 `value`。每张自拍照只能添加一次，且必须显示一张清晰的人脸。 reference_node_id: type: string nullable: true maxLength: 100 description: >- 当 `face_image_source` 为证件采集时：对于具有多个节点的身份证件验证工作流，指定要使用其自拍照的身份证件验证节点。默认使用包含该图像的最新身份证件验证。若为 `liveness` 则会被拒绝。 display_label: type: string maxLength: 512 description: 便于人类阅读的标签。当为空时，Didit 会尽可能从会话中推导出一个（例如持有人姓名和证件号码）。 comment: type: string description: 自由文本备注，例如列入名单的原因。 metadata: type: object additionalProperties: true description: >- 随条目一同存储并按原样返回的自由格式 JSON。使用 `reference_type` 和 `reference_id` 以便控制台能链接回源头。`reference_image_url` 和 `front_image_url` 仅由 Didit 设置，如果您发送它们将被丢弃。对于从会话中读取的条目，Didit 的键将与您的键合并。 properties: reference_type: type: string enum: - transaction - vendor_user - vendor_business description: '`reference_object_uuid` 指向的内容。' reference_id: type: string description: 源记录的标识符。 examples: By value: value: value: '+14155552671' comment: Reported fraud From a session: value: reference_session_id: 33333333-4444-5555-6666-777777777777 Face from a document-capture selfie: value: reference_session_id: 33333333-4444-5555-6666-777777777777 face_image_source: front_image_camera_front From a transaction: value: value: '0x52908400098527886E0F7030069857D2E4169EE7' reference_object_uuid: 55555555-6666-7777-8888-999999999999 comment: Linked to a chargeback metadata: reference_type: transaction reference_id: 55555555-6666-7777-8888-999999999999 Country: value: value: PRK comment: Sanctioned jurisdiction responses: '201': description: 条目已创建。 content: application/json: schema: $ref: '#/components/schemas/ComplianceListEntry' examples: By value: value: uuid: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee value: '+14155552671' display_label: '' comment: Reported fraud added_by: api reference_session_id: null reference_session_number: null reference_session_type: null reference_object_uuid: null metadata: null created_at: '2026-10-12T10:04:51.220391Z' Document from a session: value: uuid: bbbbbbbb-cccc-dddd-eeee-ffffffffffff value: X1234567 display_label: Jane Doe - X1234567 comment: '' added_by: api reference_session_id: 33333333-4444-5555-6666-777777777777 reference_session_number: 1042 reference_session_type: kyc reference_object_uuid: 66666666-7777-8888-9999-000000000000 metadata: full_name: Jane Doe issuing_state: ESP document_type: ID region: '' document_number: X1234567 created_at: '2026-10-12T10:06:12.774915Z' From a transaction: value: uuid: dddddddd-eeee-ffff-0000-111111111111 value: '0x52908400098527886e0f7030069857d2e4169ee7' display_label: '' comment: Linked to a chargeback added_by: api reference_session_id: null reference_session_number: null reference_session_type: null reference_object_uuid: 55555555-6666-7777-8888-999999999999 metadata: reference_type: transaction reference_id: 55555555-6666-7777-8888-999999999999 created_at: '2026-10-12T10:20:40.117062Z' '400': description: 请求体无效、该值已在列表中，或会话无法提供该值。 content: application/json: examples: Nothing to list: value: value: - >- Either 'value' or 'reference_session_id' must be provided. Duplicate value: value: value: - An entry with this value already exists in this list. Invalid phone: value: value: - >- Invalid phone number. Provide a valid international number (e.g. +1234567890). Invalid IP: value: value: - >- Invalid IP address or CIDR range (e.g. 192.168.1.1 or 10.0.0.0/24). Invalid country: value: value: - >- Invalid country code: XX. Provide a valid ISO 3166-1 alpha-2 or alpha-3 country code. Device-class fingerprint: value: value: - >- This value is a device-class fingerprint: several distinct devices have reported it, so blocklisting it would decline unrelated people. Block the user by document, face, email or phone instead. Unknown session: value: reference_session_id: - >- Session not found or does not belong to this application. No data in session: value: value: - >- Either provide a 'value' or ensure the session contains data for this entry type. Selfie on another list: value: face_image_source: - >- A document-capture selfie can only be added to the face blocklist. No clear face in selfie: value: face_image_source: - >- No clear face was found in this selfie, so it cannot be blocklisted. Selfie already listed: value: face_image_source: - This selfie is already in the blocklist. '401': description: 作用域 API 密钥已过期。其他身份验证失败将返回 `403`。 content: application/json: examples: Expired API key: value: detail: This API key has expired. '403': description: >- 缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: write`，抑或是从其允许名单之外的 IP 地址使用。 content: application/json: examples: Missing or invalid API key: value: detail: You do not have permission to perform this action. Scoped key without workflows access: value: detail: This API key has no write access to workflows. '404': description: API 密钥所属的应用中不存在具有此 UUID 的列表，或者已被删除。 content: application/json: examples: Not found: value: detail: List not found. '429': $ref: '#/components/responses/RateLimitedWrite' '503': description: 证件拍摄自拍照的人脸分析暂时不可用。未添加任何内容；请稍后重试。 content: application/json: examples: Unavailable: value: detail: Service temporarily unavailable. Please try again later. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"value": "+14155552671", "comment": "Reported fraud"}' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.lists.entries.create( "11111111-2222-3333-4444-555555555555", value="+14155552671", comment="Reported fraud", ) print(result) - lang: javascript label: Node.js source: >- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.lists.entries.create("11111111-2222-3333-4444-555555555555", { value: "+14155552671", comment: "Reported fraud", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesCreateParams{\n\tValue: didit.String(\"+14155552671\"),\n\tComment: didit.String(\"Reported fraud\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.ListsEntriesCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.lists().entries().create("11111111-2222-3333-4444-555555555555", ListsEntriesCreateParams.builder() .value("+14155552671") .comment("Reported fraud") .build()); System.out.println(result); - lang: php label: PHP source: >- lists->entries->create('11111111-2222-3333-4444-555555555555', [ 'value' => '+14155552671', 'comment' => 'Reported fraud', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.lists.entries.create( "11111111-2222-3333-4444-555555555555", value: "+14155552671", comment: "Reported fraud" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Lists.Entries.CreateAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesCreateParams { Value = "+14155552671", Comment = "Reported fraud", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: ComplianceListEntry: type: object description: 列表中的一个值。 required: - uuid - value - display_label - comment - added_by - reference_session_id - reference_session_number - reference_session_type - reference_object_uuid - metadata - created_at properties: uuid: type: string format: uuid description: 条目标识符。在“删除列表条目”中用作 `entry_uuid`。 value: type: string description: >- 列入名单的值：E.164 格式的电话号码、邮箱地址、证件号码、IP 地址或 CIDR 范围、设备指纹、钱包地址、银行账户、ISO 3166-1 alpha-3 国家/地区代码、`vendor_data`、`key` 名单上的任意字符串，或人脸名单上已存储人脸的 UUID。除电话号码和国家/地区代码外，您发送的值均以小写形式存储。匹配不区分大小写。 display_label: type: string nullable: true maxLength: 512 description: 便于人类阅读的标签。当您未提供时，Didit 会为从会话中获取的条目自动填充该标签（例如持有人姓名和证件号码）。 comment: type: string description: 自由文本备注。未设置时为空字符串。 added_by: type: string nullable: true description: >- 添加此条目的主体：`api`（API 密钥）、控制台用户的邮箱地址或 `console`、`system` 或 `migration`（Didit 创建的条目），或者 `rule`（交易或监控规则操作）。 reference_session_id: type: string format: uuid nullable: true description: 该条目来源的验证会话。如果条目是按值添加的，则为 `null`。 reference_session_number: type: integer nullable: true description: 控制台中显示的该会话在应用范围内的编号。 reference_session_type: type: string nullable: true enum: - kyc - kyb - null description: 个人验证会话为 `kyc`，企业验证会话为 `kyb`，不存在会话时为 `null`。 reference_object_uuid: type: string format: uuid nullable: true description: >- 该条目代表的记录：从会话中读取的人脸、证件、电话或邮箱记录，通过“向列表上传人脸”创建的人脸，或您发送的 UUID（例如交易 UUID 或用户的 `didit_internal_id`）。 metadata: type: object nullable: true additionalProperties: true description: >- 额外上下文。包含 Didit 设置的键（在此列出）并合并您在创建条目时发送的任何 `metadata`，按存储原样返回。无内容时为 `null`。 properties: reference_image_url: type: string description: >- 人脸条目：短期有效的签名 URL，每次调用都会重新签发；对于没有 `media: read` 权限的作用域 API 密钥为 `null`。当没有图像属于该条目时不存在。 front_image_url: type: string description: >- 包含证件正面图像的证件条目：短期有效签名 URL，每次调用都会重新签发；对于缺少 `media: read` 权限的有作用域 API 密钥，该值为 `null`。 full_name: type: string description: 从会话中提取的证件条目：持有人姓名。 issuing_state: type: string description: 从会话中提取的证件条目：ISO 3166-1 alpha-3 签发国家/地区。 document_type: type: string description: 从会话中提取的证件条目：证件类型代码，例如 `P`、`ID` 或 `DL`。 region: type: string description: 从会话中提取的证件条目：地方签发证件的签发州或省份，不适用时为空。不会由“将会话条目添加到黑名单”操作设置此项。 document_number: type: string description: 从会话中提取的证件条目：证件号码。 face_image_source: type: string enum: - front_image_camera_front - back_image_camera_front description: 取自证件拍摄自拍照的人脸条目：具体是哪张自拍照。对于活体检测人脸则不存在。 reference_node_id: type: string nullable: true description: 取自证件拍摄自拍照的人脸条目：该自拍照来源的身份证件验证节点。 fingerprint_tier: type: string nullable: true enum: - persistent_id - composite_hash - legacy_fp - unknown - null description: >- 从会话中获取的设备指纹条目：指纹的派生方式。`persistent_id` 用于标识单个设备；同一型号的设备可能会共享 `composite_hash` 和 `legacy_fp`。 sandbox: type: boolean description: 在沙盒应用中上传的人脸条目上为 `true`；此类条目不会匹配任何内容。 reference_type: type: string enum: - transaction - vendor_user - vendor_business description: 由您设置：`reference_object_uuid` 所指向的内容，以便控制台能够反向链接到该对象。 reference_id: type: string description: 由您设置：源记录的标识符。 created_at: type: string format: date-time description: 条目添加的时间。 responses: RateLimitedWrite: description: 已超出每个 API 密钥每分钟 300 次请求的共享写入限制。在重试之前请遵循 `Retry-After`。 content: application/json: schema: type: object required: - detail properties: detail: type: string example: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 您的应用 API 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.