> ## 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

> GET /v3/blocklist/：按最新排序，在一个列表中返回 Didit 会话里已加入黑名单的人脸、证件、电话号码和邮箱。



黑名单项列表 API 提示词
        将提示词复制到剪贴板



      
      

\<pre>

\`List the blocklisted faces, documents, phone numbers and email addresses of my Didit verification sessions through the Management API.

Endpoint:
GET https://verification.didit.me/v3/blocklist/

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

Goal:
\- Get one paginated feed of every session record that is currently blocklisted, to build a "Blocked" screen or audit what my team has blocked.

Behavior:
\- Items are sorted by blocklisted_at, newest first. Items of deleted sessions are not included.
\- Each item has a type ("face", "document", "phone" or "email") and the session it belongs to (session_id, session_number). Fields that do not apply to the type are null.
\- The feed covers records blocklisted from a session: with POST /v3/blocklist/add/, from the console, or with a list entry created from reference_session_id. It does not include values added to a list by hand, uploaded faces, faces taken from a document-capture selfie, or IP address, device fingerprint, wallet, bank account, user and business entries. Read those with GET /v3/lists/{list_uuid}/entries/ on the matching system blocklist.
\- face_image and front_image are short-lived signed URLs, issued again on every call; a scoped key without media: read gets null instead.

Query parameters (all optional):
\- item_type: "face" | "document" | "phone" | "email". When omitted, every type is returned.
\- limit: page size (default 50, at most 1000000).
\- offset: pagination offset (default 0).

Example call:
curl -X GET "https://verification.didit.me/v3/blocklist/?item_type=document" \
-H "x-api-key: YOUR_API_KEY"

What to read from the response:
\- count / next / previous: standard pagination envelope.
\- results[].type, session_id, session_number, blocklisted_at.
\- face items: face_image.
\- document items: document_type (for example "P" passport, "ID" national ID, "DL" driver's license), document_number, front_image.
\- phone items: phone_number (E.164), country_code (ISO 3166-1 alpha-2).
\- email items: email.

Failure modes:
\- 400: an unknown item_type, 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.
\- 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>



      
      

粘贴到

列出您验证会话中当前已加入黑名单的人脸、身份证件、电话号码和邮箱地址，按时间倒序排列（最新的在前）。每一项都指向其来源会话，您可以在控制台中打开该会话，或获取其决策。此列表仅显示**来自会话**的黑名单记录：通过[添加到黑名单](https://docs.didit.me/zh/management-api/blocklist/add.md)、在控制台中手动添加，或通过从 `reference_session_id` 创建的[名单条目](https://docs.didit.me/zh/management-api/lists/create-entry.md)添加。在名单中手动输入的值、[已上传的人脸](https://docs.didit.me/zh/management-api/lists/upload-face.md)、从证件采集过程中的自拍照中获取的人脸，以及其他类型的条目（地址、设备指纹、钱包、银行账户、用户、企业），仅存在于系统黑名单中。请使用[名单条目](https://docs.didit.me/zh/management-api/lists/list-entries.md)读取这些记录。关于黑名单在控制台中的工作方式，请参阅[黑名单用户](https://docs.didit.me/zh/console/blocklist-users.md)。


## OpenAPI

````yaml zh/openapi-25.json GET /v3/blocklist/
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/blocklist/:
    get:
      tags:
        - Blocklist
      summary: 列出黑名单项
      description: >-
        返回当前已列入黑名单的应用验证会话的人脸、身份证件、电话号码和邮箱地址的分页信息流，按 `blocklisted_at` 由新到旧排序；使用
        `item_type`
        进行过滤。已删除会话的项目不包含在内。该信息流涵盖通过会话列入黑名单的记录（通过[将会话项目添加到黑名单](https://docs.didit.me/zh/management-api/blocklist/add)、从控制台添加，或通过基于会话创建的名单条目）；手动添加到名单的值、上传的人脸、来自证件采集流程中自拍照的人脸以及其他条目类型请使用[列出名单条目](https://docs.didit.me/zh/management-api/lists/list-entries)读取。`face_image`
        和 `front_image` 是短期有效的已签名 URL，未拥有 `media: read` 权限的作用域 API 密钥将接收到
        `null`。作用域 API 密钥需要 `workflows: read` 权限。
      operationId: list_blocklist_items
      parameters:
        - name: item_type
          in: query
          required: false
          description: 仅包含此类型的项。省略时，返回所有类型。
          schema:
            type: string
            enum:
              - face
              - document
              - phone
              - email
        - 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/BlocklistedItem'
              examples:
                Mixed feed:
                  value:
                    count: 2
                    next: null
                    previous: null
                    results:
                      - type: document
                        session_id: 33333333-4444-5555-6666-777777777777
                        session_number: 1042
                        blocklisted_at: '2026-10-12T10:06:12.701553Z'
                        face_image: null
                        document_type: ID
                        document_number: X1234567
                        front_image: >-
                          https://media.example.com/documents/front.jpg?expires=1760263938&signature=8b2e47
                        phone_number: null
                        country_code: null
                        email: null
                      - type: phone
                        session_id: 77777777-8888-9999-0000-111111111111
                        session_number: 1017
                        blocklisted_at: '2026-10-08T15:31:09.400127Z'
                        face_image: null
                        document_type: null
                        document_number: null
                        front_image: null
                        phone_number: '+14155552671'
                        country_code: US
                        email: null
        '400':
          description: 查询参数无效。
          content:
            application/json:
              examples:
                Unknown item type:
                  value:
                    item_type:
                      - '"wallet" is not a valid choice.'
                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.
        '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/blocklist/?item_type=document' \
              -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.blocklist.list():
                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.blocklist.list()) {
              console.log(item);
            }
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Blocklist.ListAutoPaging(ctx, didit.BlocklistListParams{})\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.blocklist().list()) {
                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->blocklist->list() as $item) {
                print_r($item->toArray());
            }
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            didit.blocklist.list.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.Blocklist.ListAsync())
            {
                Console.WriteLine(JsonSerializer.Serialize(item));
            }
components:
  schemas:
    BlocklistedItem:
      type: object
      description: 验证会话中的一个黑名单人脸、身份证件、电话号码或邮箱地址。不适用于该项目 `type` 的字段为 `null`。
      required:
        - type
        - session_id
        - session_number
        - blocklisted_at
        - face_image
        - document_type
        - document_number
        - front_image
        - phone_number
        - country_code
        - email
      properties:
        type:
          type: string
          enum:
            - face
            - document
            - phone
            - email
          description: 被列入黑名单的内容。
        session_id:
          type: string
          format: uuid
          description: 该项所属的验证会话。
        session_number:
          type: integer
          nullable: true
          description: 控制台中显示的该会话在应用范围内的编号。
        blocklisted_at:
          type: string
          format: date-time
          description: 该项最后被列入黑名单的时间。
        face_image:
          type: string
          nullable: true
          description: >-
            人脸条目：短期有效的签名 URL，每次调用都会重新签发；对于没有 `media: read` 权限的作用域 API 密钥为
            `null`。当未存储参考图像时也为 `null`。
        document_type:
          type: string
          nullable: true
          description: 证件条目：证件类型代码，例如 `P`（护照）、`ID`（国民身份证）、`DL`（驾照）或 `RP`（居留许可）。
        document_number:
          type: string
          nullable: true
          description: 证件条目：证件号码，若证件无证件号码则为个人号码。
        front_image:
          type: string
          nullable: true
          description: >-
            证件条目：证件正面图像，短期有效签名 URL，每次调用都会重新签发；对于缺少 `media: read` 权限的有作用域 API
            密钥，该值为 `null`。
        phone_number:
          type: string
          nullable: true
          description: 电话条目：E.164 格式的电话号码。
        country_code:
          type: string
          nullable: true
          description: 电话条目：该号码的 ISO 3166-1 alpha-2 国家/地区。
        email:
          type: string
          nullable: true
          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.