> ## 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 提供 GET /v3/lists/{list_uuid}/entries/ 接口，可分页查询黑名单、白名单或自定义名单中的条目，并支持搜索过滤。按次计费。



列表条目 API 提示词
        将提示词复制到剪贴板



      
      

\<pre>

\`Retrieve paginated entries from a Didit list through the Management API.

Endpoint:
GET 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: read.

Goal:
\- Browse, search, or export the entries inside a specific list (blocklist, allowlist, or custom).

Path parameter:
\- list_uuid: the list UUID from GET /v3/lists/.

Query parameters (all optional):
\- search: case-insensitive text that value or display_label must contain.
\- reference_session_id: only the entries taken from this person verification session (for example, to see which of its faces are already in the face blocklist). Must be a session UUID.
\- limit: page size (default 50, at most 1000000).
\- offset: pagination offset (default 0).

Behavior:
\- Current entries only, newest first.
\- Image URLs in metadata (reference_image_url, front_image_url) are short-lived signed URLs, issued again on every call. A scoped key without media: read gets null in their place.

Example call:
curl -X GET "https://verification.didit.me/v3/lists/{list_uuid}/entries/?search=example.com" \
-H "x-api-key: YOUR_API_KEY"

What to read from the response:
\- count / next / previous: standard pagination envelope.
\- results[].uuid: entry id; use it as entry_uuid in DELETE /v3/lists/{list_uuid}/entries/{entry_uuid}/.
\- results[].value: the listed value (phone number in E.164, email, document number, IP or CIDR range, wallet address, country code, vendor_data, or a face UUID on face lists). Matching is case-insensitive.
\- results[].display_label, comment: labels and notes.
\- results[].added_by: "api" (an API key), a console user's email or "console", "system" (entries Didit provisions), or "rule" (a transaction rule action).
\- results[].reference_session_id / reference_session_number / reference_session_type: set when the entry was taken from a verification session; reference_session_type is "kyc" or "kyb".
\- results[].reference_object_uuid + metadata.reference_type: the record the entry stands for. metadata.reference_type, when you set it, says whether reference_object_uuid is a "transaction", a "vendor_user" or a "vendor_business".
\- results[].metadata: may include document context (full_name, issuing_state, document_type, document_number), face image URLs, and, for faces from a document-capture selfie, face_image_source and reference_node_id.

Failure modes:
\- 400: reference_session_id is not a valid UUID, or limit/offset above 1000000.
\- 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: read.
\- 404: no list with this UUID in this application, or it was deleted ({ "detail": "List not found." }).
\- 429: rate limited (see /integration/rate-limiting); back off and retry.

Side effects: none. This is a pure read.

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

\</pre>



      
      

粘贴到

按时间倒序（最新的在前）检索某个列表的条目，并可选择搜索。`search` 会匹配条目值或标签的部分内容，且不区分大小写。`reference_session_id` 会将结果缩小为来自某一次验证会话的条目。在人脸列表中，`metadata.face_image_source` 用于标明每个条目对应会话中的哪张人脸（缺省时为 `liveness`）。人脸和证件条目的 `metadata` 中包含图片 URL，这些 URL 在调用后很快失效。请重新获取条目以获得新的 URL，而不要存储这些 URL。未具备 **media: read** 权限的 API 密钥，这些 URL 将返回 `null`。


## OpenAPI

````yaml zh/openapi-25.json GET /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/:
    get:
      tags:
        - Lists
      summary: 列出名单条目
      description: >-
        按由新到旧的顺序返回单个名单的当前条目。`search` 会不区分大小写地匹配条目的部分 `value` 或 `display_label`，而
        `reference_session_id` 则将结果缩小为取自某个人验证会话的条目。`metadata` 中的图片 URL
        是在每次调用时重新签发的短期有效签名 URL；未拥有 `media: read` 权限的作用域 API 密钥将在相应位置接收到
        `null`。作用域 API 密钥需要 `workflows: read` 权限。
      operationId: list_list_entries
      parameters:
        - name: list_uuid
          in: path
          required: true
          description: 列表的 UUID，如列出列表或创建列表所返回。
          schema:
            type: string
            format: uuid
          example: 11111111-2222-3333-4444-555555555555
        - name: search
          in: query
          required: false
          description: 条目的 `value` 或 `display_label` 必须包含的不区分大小写的文本。
          schema:
            type: string
        - name: reference_session_id
          in: query
          required: false
          description: 仅从该人员验证会话中获取的条目，例如查看其哪些人脸已被列出。
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          required: false
          description: 页面大小。默认为 50。大于 1000000 的值返回 `400`；0、负数或非数字值将回退为 50。
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 1000000
        - name: offset
          in: query
          required: false
          description: 要返回的第一项的从零开始的索引。建议跟随 `next`。大于 1000000 的值将返回 `400`；负数或非数字值将回退为 0。
          schema:
            type: integer
            maximum: 1000000
            minimum: 0
            default: 0
      responses:
        '200':
          description: 一页条目，按最新优先排序。
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - next
                  - previous
                  - results
                properties:
                  count:
                    type: integer
                    minimum: 0
                    description: 符合过滤条件的条目总数。
                  next:
                    type: string
                    format: uri
                    nullable: true
                    description: 下一页的绝对 URL，最后一页则为 `null`。
                  previous:
                    type: string
                    format: uri
                    nullable: true
                    description: 上一页的绝对 URL，第一页则为 `null`。
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ComplianceListEntry'
              examples:
                Entries:
                  value:
                    count: 2
                    next: null
                    previous: null
                    results:
                      - 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'
                      - uuid: eeeeeeee-ffff-0000-1111-222222222222
                        value: y7654321
                        display_label: ''
                        comment: Reported by a partner
                        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-03T07:48:30.552810Z'
        '400':
          description: 查询参数无效。
          content:
            application/json:
              examples:
                Invalid session id:
                  value:
                    reference_session_id:
                      - Must be a valid UUID.
                Limit too large:
                  value:
                    - limit must not exceed 1000000.
        '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: read`，抑或是从其允许名单之外的 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 read access to workflows.
        '404':
          description: API 密钥所属的应用中不存在具有此 UUID 的列表，或者已被删除。
          content:
            application/json:
              examples:
                Not found:
                  value:
                    detail: List not found.
        '429':
          description: 已超出每个 API 密钥每分钟 600 次请求的共享读取限制。在重试之前请遵循 `Retry-After`。
          content:
            application/json:
              examples:
                Rate limited:
                  value:
                    detail: >-
                      GET request rate limit exceeded. You can make up to 600
                      requests per minute.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl -X GET
            'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/?search=example.com'
            \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            for item in client.lists.entries.list(
                "11111111-2222-3333-4444-555555555555",
            ):
                print(item)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            for await (const item of
            didit.lists.entries.list("11111111-2222-3333-4444-555555555555")) {
              console.log(item);
            }
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Lists.Entries.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            for (var item :
            client.lists().entries().list("11111111-2222-3333-4444-555555555555"))
            {
                System.out.println(item);
            }
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            foreach
            ($didit->lists->entries->list('11111111-2222-3333-4444-555555555555')
            as $item) {
                print_r($item->toArray());
            }
        - lang: ruby
          label: Ruby
          source: >-
            require "didit"


            # Reads DIDIT_API_KEY.

            didit = Didit::Client.new


            didit.lists.entries.list("11111111-2222-3333-4444-555555555555").auto_paging_each
            do |item|
              puts item.to_h
            end
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            await foreach (var item in await
            client.Lists.Entries.ListAsync("11111111-2222-3333-4444-555555555555"))

            {
                Console.WriteLine(JsonSerializer.Serialize(item));
            }
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: 条目添加的时间。
  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.