> ## 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：筛选 KYC 与 KYB 会话

> 通过 GET /v3/sessions/ 列出验证会话，可按类型、状态、工作流和供应商数据筛选。Didit 统一 KYC + KYB API，按次计费。



列出会话提示词
        将提示词复制到剪贴板



      
      

\<pre>

\`List Didit verification sessions for your application with filters and pagination.

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

Authentication:
Use the x-api-key header with your Didit API key. The key must hold read:sessions.

Query parameters:
\- session_kind ("user" | "business" | "all", default "user") — chooses which kind to list. "user" returns only KYC sessions (backward-compatible default). "business" returns only KYB. "all" concatenates both (KYB rows are appended; not interleaved by timestamp).
\- vendor_data (string) — exact match on your stable identifier.
\- didit_internal_id (UUID) — matches vendor_user_id.
\- status (one or more, comma-separated) — Approved, Declined, In Review, In Progress, Not Started, Expired, Abandoned, Kyc Expired, Resubmitted, Awaiting User.
\- workflow_id (one or more UUIDs, comma-separated).
\- country (one or more ISO-3 codes, comma-separated) — issuing-state for KYC, country_code for KYB.
\- region (one or more, comma-separated).
\- document_type (one or more, comma-separated).
\- date_from, date_to (ISO 8601 date) — inclusive on created_at.
\- search (string) - a complete displayed reference such as S-0001 (user) or B-0001 (business) matches only that session number and kind, ignoring leading zeros and letter case.
Other input searches the existing name, contact, document, registration-number and vendor_data fields.
\- tags (comma-separated tag ids) — sessions that carry any of them.
\- decided_from, decided_to (ISO 8601 datetimes) — sessions whose status last changed at or after / before the value.
\- limit (int, default 50), offset (int, default 0) — limit/offset pagination. Both accept values up to 1000000; larger values return 400.

Per-kind filters (silently ignored on the other kind): is_kyc_to_be_reviewed, status_initialized_as_in_review, session_type, api_service, screened_full_name, document_name, warning.

curl example:
curl -G https://verification.didit.me/v3/sessions/ \
-H "x-api-key: <API_KEY>" \
\--data-urlencode "session_kind=all" \
\--data-urlencode "status=Approved,In Review" \
\--data-urlencode "date_from=2026-01-01" \
\--data-urlencode "limit=50"

Response envelope:
\{
"count": <int>,   // exact up to 100, capped at 100 beyond that: paginate with next
"next": "<url|null>",
"previous": "<url|null>",
"results": [ ...rows ]
}

Every row has:
\- session_id (UUID), session_kind ("user" | "business"), session_number, status, vendor_data, created_at.

KYC row extras: portrait_image, document_type, full_name, country (issuing state), phone_number, email_address, features, didit_internal_id, assignee, waiting_since, sla_due_at, top_warnings, warnings_count.

KYB row extras: workflow_type, workflow_label, company_name, registration_number, country (incorporation).

Each row is a LIGHT projection. For the full feature payload of a row, call GET /v3/session/{session_id}/decision/ — see /sessions-api/retrieve-session.

Failure modes:
\- 401 — invalid API key.
\- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks read:sessions.
\- 400 — malformed UUIDs in filters are silently dropped (no error); malformed ISO dates return { "date_from": ["..."] }.

Common patterns:
\- Build a dashboard: paginate with limit + offset, sort newest-first (server orders by -session_number within each kind).
\- Find pending review queue: status=In Review.
\- Find a specific entity's sessions: vendor_data=<your-id>.
\- Refresh ongoing AML hits: filter by workflow_id of your AML workflow.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\</pre>



      
      

粘贴到

## 会话类型过滤器使用 `session_kind` 查询参数选择要返回的会话类型：| 值 | 返回内容 |
| - | - |
| `user`（默认） | 仅返回用户验证（KYC）会话。**向后兼容的行为**：如需获得此结果，请省略 `session_kind`。 |
| `business` | 仅返回企业验证（KYB）会话。 |
| `all` | 同时返回用户验证和企业验证会话，并将两者依次拼接。 |响应中的每一行都包含 `session_kind: "user" | "business"`，便于您的客户端逐行根据结构进行分支处理。## 通用过滤器以下过滤器同时适用于两种类型（仅适用于用户的过滤器在 `session_kind=business` 时会被忽略，反之亦然）：| 查询参数 | 说明 |
| - | - |
| `session_kind` | `user`、`business` 或 `all`。默认为 `user`。 |
| `vendor_data` | 与您的标识符完全匹配。 |
| `status` | 一个或多个状态，以逗号分隔，须与 API 返回的写法完全一致：`Approved`、`Declined`、`In Review` 等（参见[验证状态](https://docs.didit.me/zh/integration/verification-statuses.md)）。 |
| `workflow_id` | 按所用工作流进行过滤。 |
| `country` | 国家/地区代码过滤器（用户：`issuing_states`；企业：`country_code`）。 |
| `date_from`、`date_to` | 创建日期范围（ISO 8601 格式）。 |
| `tags` | 以逗号分隔的标签 ID。返回包含其中任一标签的会话。 |
| `decided_from`、`decided_to` | ISO 8601 格式的日期时间。返回状态最后一次变更时间位于该范围内的会话（包含起始时间，不包含结束时间）。此处使用的是最后一次状态变更的时间，而非创建时间。 |
| `search` | 完整显示的编号，例如 `S-0001` 或 `B-0001`，仅匹配该会话编号和类型，忽略前导零和字母大小写。其他输入将搜索现有的名称、联系人、证件、注册号和 `vendor_data` 字段。 |## 示例> [tab] 列出用户验证（KYC）会话（默认）
>
> ```bash theme={null}
> curl -G https://verification.didit.me/v3/sessions/ \
>   -H "x-api-key: YOUR_API_KEY" \
>   --data-urlencode "vendor_data=user-42"
> ```
>
> **响应（已截断）：**
>
> ```json theme={null}
> {
>   "count": 3,
>   "next": null,
>   "previous": null,
>   "results": [
>     {
>       "session_id": "...",
>       "session_kind": "user",
>       "session_number": 1024,
>       "session_url": "...",
>       "portrait_image": "...",
>       "document_type": "Passport",
>       "full_name": "John Doe",
>       "country": "GBR",
>       "status": "Approved",
>       "vendor_data": "user-42",
>       "didit_internal_id": "...",
>       "created_at": "2026-04-10T09:00:00Z",
>       "features": "ID_VERIFICATION,LIVENESS,FACE_MATCH,AML",
>       "phone_number": "+14155550123",
>       "email_address": "jane@example.com",
>       "additional_details": null
>     }
>   ]
> }
> ```> [tab] 列出企业验证（KYB）会话
>
> ```bash theme={null}
> curl -G https://verification.didit.me/v3/sessions/ \
>   -H "x-api-key: YOUR_API_KEY" \
>   --data-urlencode "session_kind=business" \
>   --data-urlencode "status=Approved"
> ```
>
> **响应（已截断）：**
>
> ```json theme={null}
> {
>   "count": 1,
>   "next": null,
>   "previous": null,
>   "results": [
>     {
>       "session_id": "...",
>       "session_kind": "business",
>       "session_number": 89,
>       "status": "Approved",
>       "vendor_data": "biz-acme-001",
>       "created_at": "2026-04-01T09:00:00Z",
>       "workflow_id": "wf_kyb_standard",
>       "workflow_type": "business",
>       "workflow_label": "Standard KYB",
>       "company_name": "Acme Corporation Limited",
>       "registration_number": "12345678",
>       "country": "GBR"
>     }
>   ]
> }
> ```> [tab] 列出两种类型的会话
>
> ```bash theme={null}
> curl -G https://verification.didit.me/v3/sessions/ \
>   -H "x-api-key: YOUR_API_KEY" \
>   --data-urlencode "session_kind=all" \
>   --data-urlencode "date_from=2026-04-01T00:00:00Z"
> ```
>
> 用户验证和企业验证的行会返回在同一个 `results` 数组中。使用方应根据 `session_kind` 逐行进行分支处理。
>
> > [!NOTE]
> >
> > `all` 模式是将结果依次拼接，而不是按时间戳交错排列。对于高数据量的混合遍历，请分别调用每种类型，并在客户端合并结果。## 各类型的行结构不同用户验证（KYC）行包含：`portrait_image`、`document_type`、`full_name`、`country`（签发州）、`phone_number`、`email_address`，以及一些审核字段：`assignee`（持有该会话的控制台审核员，无则为 `null`）、`waiting_since` 和 `sla_due_at`（仅在会话处于 `In Review` 时设置）、`top_warnings`（最重要的警告，每项包含 `risk`、`feature`、`log_type` 和 `short_description`）以及 `warnings_count`。企业验证（KYB）行包含：`workflow_type`、`workflow_label`、`company_name`、`registration_number`、`country`（注册成立国家/地区）。两者都包含：`session_id`、`session_kind`、`session_number`、`status`、`vendor_data`、`created_at`。完整的功能矩阵请参见[会话概览](https://docs.didit.me/zh/sessions-api/overview.md)。## 分页分页使用 `limit`（默认 `50`）和 `offset`（默认 `0`），响应中包含绝对 `next` 和 `previous` URL。两个参数的取值上限均为 `1000000`；超过该值将返回 `400`。`count` 在 `100` 以内是精确值，超过后始终保持为 `100`，因此请勿将其用作总数。请持续请求 `next` URL，直到其值为 `null`。使用 `session_kind=all` 时，`count` 是两种类型之和，每种类型各自上限为 `100`。## 相关内容- [会话概览](https://docs.didit.me/zh/sessions-api/overview.md)
- [获取会话](https://docs.didit.me/zh/sessions-api/retrieve-session.md)：单个会话行的完整决策
- [企业概览](https://docs.didit.me/zh/entities/businesses/overview.md)：跨会话聚合的企业实体
- [用户概览](https://docs.didit.me/zh/entities/users/overview.md)：跨会话聚合的用户实体


## OpenAPI

````yaml zh/openapi-25.json GET /v3/sessions/
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/sessions/:
    get:
      tags:
        - Sessions
      summary: 带过滤器和分页列出验证会话（KYC 和/或 KYB）
      description: >-
        返回由您的 API 密钥标识的应用的验证会话分页列表，按从新到旧排序（降序 `session_number`）。


        **规范 URL：** 路由为 `/v3/sessions/`（带有末尾斜杠）。针对不带斜杠的 `/v3/sessions` 请求会收到
        `301` 重定向至带有斜杠的 URL，并保留查询字符串；大多数 HTTP 客户端会在 GET 请求中透明地遵循该重定向。


        **何时使用此 endpoint 与 Webhook：** 在仪表板、后台搜索、对账和批量导出场景中使用此
        endpoint。请勿通过轮询此接口来跟踪单个验证的进度；请改为配置
        [Webhook](/zh/integration/webhooks)，它会在会话发生变更的瞬间推送 `status.updated`
        事件。如需获取单个会话的完整结果，请调用 `GET /v3/session/{sessionId}/decision/`。


        **KYC 与 KYB 会话：** `session_kind` 用于选择列出的会话类型：

        - `user`（默认值）- 仅列出用户验证（KYC）会话。向后兼容的行为。

        - `business` - 仅列出企业验证（KYB）会话。数据行具有不同且更精简的结构（参见响应模式）。

        - `all` - 在一个响应中同时返回两种类型：相同 `limit`/`offset` 下的 KYC 页面和 KYB 页面会在
        `results` 中拼接（KYC 行在前），因此一个页面最多可包含 `2 x limit` 行。`count` 为两种类型的总和，而
        `next`/`previous` 反映 KYC 侧的分页。如需对混合数据进行严格分页，请分别调用 `user` 和 `business`。


        每一行都包含一个 `session_kind` 鉴别字段（`"user"` 或 `"business"`）。


        **分页：** 标准 limit/offset：`limit`（默认 50）和 `offset`（默认 0），并提供
        `next`/`previous` 开箱即用的页面 URL。对于 KYC 行，`count` 是精确的。对于 KYB 行，`count`
        是通过有界扫描计算的，上限为 100；当匹配数超过 100 时它仍保持为 100，因此请使用 `next`
        进行迭代（或通过检查返回的数据是否已满一页），而不要根据 `count` 计算总页数。


        **过滤器语义：** 所有过滤器均以 AND 组合并应用于 KYC 行。当 `session_kind` 为 `business` 或
        `all` 时，KYB
        侧支持以下通用参数：`vendor_data`、`status`、`workflow_id`、`country`（登记公司国家/地区代码）、`date_from`、`date_to`、`search`（公司名称、注册号
        — 输入注册号时请勿包含分隔符，例如 `DPC001` 而不是 `DPC-001` — vendor_data、会话编号或会话
        UUID）、`warning` 和 `organization_name`；其余仅适用于 KYC 的过滤器在 KYB
        行中将被忽略。逗号分隔的参数（`status`、`country`、`document_type`、`region`、`workflow_id`、`document_name`、`warning`、`organization_name`、`session_type`）匹配列出的任意值（参数内为
        OR 关系）。`vendor_data` 为精确匹配；如需部分匹配请使用
        `search`。列表过滤器中的未知值不会返回任何行（不会报错）；类型参数中格式错误的值（`date_from`、`date_to`、`didit_internal_id`、`api_service`、`session_kind`）将返回
        `400` 并附带针对各字段的错误对象。


        **搜索：** `search` 会自适应输入内容：完整 UUID 用于查询 `session_id`；数字（可选包含 `+ - .
        space`）匹配会话编号前缀、证件/个人编号、电话号码前缀或 `vendor_data`；包含 `@`
        的值匹配邮箱前缀；任何其他文本匹配姓名（不区分重音符号）和 `vendor_data`。


        未对此 endpoint 强制实施固定的速率限制，但请保持较低的列表轮询频率，并依靠 Webhook 获取实时更新。
      operationId: get_v3_sessions
      parameters:
        - name: session_kind
          in: query
          required: false
          description: >-
            要列出哪种类型的会话：`user`（仅限 KYC，默认值）、`business`（仅限 KYB）或
            `all`（两者合并，有关合并分页语义请参阅说明）。匹配不区分大小写（`BUSINESS` 有效）；除
            `user`/`business`/`all` 的大小写变体之外的任何值都会返回 `400`。
          schema:
            type: string
            enum:
              - user
              - business
              - all
            default: user
          example: all
        - name: limit
          in: query
          required: false
          description: 每页最大行数（当 `session_kind=all` 时按每种类型计算）。默认值为 50。
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 1000000
          example: 20
        - name: offset
          in: query
          required: false
          description: 返回第一行前跳过的行数。默认为 0。建议优先使用响应中的 `next`/`previous` URL。
          schema:
            type: integer
            maximum: 1000000
            minimum: 0
            default: 0
          example: 20
        - name: status
          in: query
          required: false
          description: >-
            要包含的会话状态的逗号分隔列表，例如 `Approved,In
            Review`。值区分大小写；请参阅[验证状态](/zh/integration/verification-statuses)。未知值不会匹配任何内容。
          schema:
            type: string
          example: Approved,In Review
        - name: vendor_data
          in: query
          required: false
          description: 对您在创建会话时发送的 `vendor_data`（您自己的用户/企业标识符）进行精确匹配过滤。如需部分匹配，请改用 `search`。
          schema:
            type: string
          example: your-user-id-123
        - name: search
          in: query
          required: false
          description: >-
            完整的显示引用（例如用户的 `S-0001` 或企业的
            `B-0001`）仅匹配该会话编号和类型；前导零和字母大小写不影响匹配。智能自由文本搜索。完整的 UUID 匹配
            `session_id`；数字输入匹配会话编号前缀、证件/个人编号、电话前缀或 `vendor_data`；包含 `@`
            的输入匹配邮箱前缀；其他文本匹配姓名（不区分重音符号）和
            `vendor_data`。包含数字的自由文本还会额外匹配证件/个人编号搜索字段和会话编号前缀。
          schema:
            type: string
          example: jane doe
        - name: workflow_id
          in: query
          required: false
          description: 以逗号分隔的工作流 UUID 列表（可在控制台的工作流页面中找到）。列表中格式错误的 UUID 将被忽略；若无有效值，则结果为空。
          schema:
            type: string
          example: 9f9b1234-aaaa-bbbb-cccc-1234567890ab
        - name: date_from
          in: query
          required: false
          description: 仅包含在此日期或之后创建的会话（UTC），格式为 `YYYY-MM-DD`。格式错误的日期返回 `400`。
          schema:
            type: string
            format: date
          example: '2026-06-01'
        - name: date_to
          in: query
          required: false
          description: >-
            仅包含截至此日期创建的会话（UTC），格式为 `YYYY-MM-DD`。对于 KYC 行，包含全天；对于 KYB 行，比较条件为
            `created_at <= date_to`（午夜），因此请使用下一天的日期以包含整天的 KYB 会话。
          schema:
            type: string
            format: date
          example: '2026-06-30'
        - name: tags
          in: query
          required: false
          schema:
            type: string
          description: >-
            逗号分隔的标签 ID（您应用的 `tags`）。返回带有其中任意标签的会话。非有效 UUID 的 ID 将被忽略，当没有任何有效 ID
            时，列表为空。
        - name: decided_from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: ISO 8601 日期时间。返回状态最后变更时间等于或晚于该时间的会话。该参数根据最后状态变更时间进行过滤，而非根据创建时间。
        - name: decided_to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: ISO 8601 日期时间。返回状态最后变更时间早于该时间的会话。可与 `decided_from` 结合使用以构成半开区间。
        - name: country
          in: query
          required: false
          description: >-
            以逗号分隔的国家/地区过滤器。对于 KYC 行：身份证件签发国家/地区的 ISO 3166-1 alpha-3 代码（例如
            `ESP,USA`），可能与国籍不同。对于 KYB 行：注册公司的国家/地区代码。
          schema:
            type: string
          example: ESP,USA
        - name: document_type
          in: query
          required: false
          description: >-
            会话中已验证的以逗号分隔的身份证件类型代码（仅限 KYC
            行）：`P`（护照）、`ID`（身份证）、`DL`（驾照）、`RP`（居留许可）、`SSC`（社保卡）、`HIC`（健康保险卡）、`WP`（工作许可）、`TC`（税卡）、`VISA`、`PSC`（公共服务卡）、`BC`（出生证明）、`OTHER`。请注意，响应字段
            `document_type` 包含的是显示名称，而非代码。
          schema:
            type: string
          example: P,ID
        - name: document_name
          in: query
          required: false
          description: >-
            确切的证件名称；多个名称可使用逗号分隔传递，但只有当值包含多个 ` - `
            分隔符时才会按逗号拆分（包含内嵌逗号的单个名称会进行整体匹配）。名称与证件验证（正面或背面）识别的名称一致，例如 `Spain - Id
            Card (2021)`。仅适用于 KYC 记录。
          schema:
            type: string
          example: Spain - Id Card (2021)
        - name: region
          in: query
          required: false
          description: 以逗号分隔的证件所属地区/州值（适用于按地区签发的证件，例如美国驾照）。仅限 KYC 行。
          schema:
            type: string
          example: CA,TX
        - name: didit_internal_id
          in: query
          required: false
          description: >-
            按 Didit 的内部用户标识符（响应字段
            `didit_internal_id`）进行过滤，以列出某个已验证用户的所有会话。必须是有效的 UUID；格式错误的值将返回
            `400`。仅限 KYC 行。
          schema:
            type: string
            format: uuid
          example: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147
        - name: session_type
          in: query
          required: false
          description: >-
            逗号分隔的会话创建渠道：`API`、`HOSTED`、`MIGRATED`。特殊值 `ALL`（或省略该参数）将禁用此过滤器。仅适用于
            KYC 记录。
          schema:
            type: string
          example: HOSTED
        - name: api_service
          in: query
          required: false
          description: 按服务过滤独立 API 会话。无效值将返回 `400`。仅适用于 KYC 行。
          schema:
            type: string
            enum:
              - ID_VERIFICATION
              - FACE_MATCH
              - AGE_ESTIMATION
              - FACE_SEARCH
              - POA
              - AML
              - KYB_REGISTRY
              - PASSIVE_LIVENESS
              - DATABASE_VALIDATION
              - PHONE_VERIFICATION
              - EMAIL_VERIFICATION
          example: AML
        - name: screened_full_name
          in: query
          required: false
          description: >-
            在 AML 和数据库核验筛查数据中进行不区分重音符号的姓名搜索。当与 `api_service=AML` 或
            `api_service=DATABASE_VALIDATION` 结合使用时，搜索将仅限于该功能的筛查数据。仅限 KYC 数据行。
          schema:
            type: string
          example: Jane Doe
        - name: warning
          in: query
          required: false
          description: >-
            逗号分隔的警告风险代码；返回触发了其中任意风险代码的会话（例如
            `POSSIBLE_FRAUD`）。各个功能的风险代码已在[警告文档](/zh/integration/webhooks)中列出。适用于
            KYC 记录，并且配合企业警告代码时也适用于 KYB 记录。
          schema:
            type: string
          example: POSSIBLE_FRAUD
        - name: status_initialized_as_in_review
          in: query
          required: false
          description: 为 `true` 时，仅包含其决策最初为 `In Review` 的会话（用于审计人工审核量）。仅限 KYC 行。
          schema:
            type: boolean
          example: true
        - name: is_kyc_to_be_reviewed
          in: query
          required: false
          description: '`true` 返回证件验证被标记为需要人工审核的会话；`false` 返回证件验证明确未被标记的会话。省略以禁用。仅限 KYC 行。'
          schema:
            type: boolean
          example: true
        - name: euuid
          in: query
          required: false
          description: >-
            按终端用户的 euuid（分配给验证用户的 UUID，用于 Console 深度链接）过滤。必须是有效的 UUID；格式错误的取值会返回
            400 字段错误。仅适用于 KYC 行。
          schema:
            type: string
            format: uuid
          example: 0f8fad5b-d9cb-469f-a165-70867728950e
        - name: organization_name
          in: query
          required: false
          description: 逗号分隔的组织名称。面向控制台；使用 API 密钥（已限定为单个应用）时，它仅匹配您自己组织的名称。
          schema:
            type: string
          example: Acme Inc
      responses:
        '200':
          description: >-
            分页会话列表。`results` 中的各项根据 `session_kind` 可能为 KYC 行、KYB 行或两者皆有；可通过每行的
            `session_kind` 字段进行区分。
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - next
                  - previous
                  - results
                properties:
                  count:
                    type: integer
                    description: >-
                      匹配过滤条件的会话数量：100 以内为准确数值，超过 100 时封顶显示为 100，因此请勿将其视为总数。请使用
                      `next` 判断是否存在更多页面。对于
                      `session_kind=all`，它是两种类型的总和，每种类型各自封顶显示为 100。
                    example: 2
                  next:
                    type: string
                    format: uri
                    nullable: true
                    description: 下一页的绝对 URL，最后一页则为 `null`。
                    example: >-
                      https://verification.didit.me/v3/sessions/?limit=20&offset=20
                  previous:
                    type: string
                    format: uri
                    nullable: true
                    description: 上一页的绝对 URL，第一页则为 `null`。
                    example: null
                  results:
                    type: array
                    description: 会话行，最新的排在最前。使用 `session_kind=all` 时，KYC 行排在最前，然后是 KYB 行。
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/UserSessionListItem'
                        - $ref: '#/components/schemas/BusinessSessionListItem'
                      discriminator:
                        propertyName: session_kind
                        mapping:
                          user: '#/components/schemas/UserSessionListItem'
                          business: '#/components/schemas/BusinessSessionListItem'
              examples:
                KYC sessions (default):
                  summary: session_kind=user - 一个已完成的会话和一个未开始的会话
                  value:
                    count: 2
                    next: null
                    previous: null
                    results:
                      - session_id: 5b3720ed-d429-42ef-b67f-37ea805f48ee
                        session_kind: user
                        session_number: 720
                        session_url: https://verify.didit.me/session/CuXoBYCYVO5Y
                        portrait_image: >-
                          https://<media-host>/portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=...
                        document_type: Passport
                        full_name: Jane Marie Doe
                        country: ESP
                        status: Approved
                        vendor_data: your-user-id-123
                        didit_internal_id: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147
                        created_at: '2026-06-09T12:26:54.328364Z'
                        features:
                          - feature: ID_VERIFICATION
                            status: Approved
                          - feature: LIVENESS
                            status: Approved
                          - feature: FACE_MATCH
                            status: Approved
                          - feature: AML
                            status: Approved
                          - feature: IP_ANALYSIS
                            status: Approved
                        phone_number:
                          number: '+14155552671'
                          is_verified: true
                        email_address:
                          email: jane@example.com
                          is_verified: true
                        additional_details:
                          aml:
                            total_hits: 0
                            entity_type: person
                            is_adverse_media_fetched: false
                          liveness:
                            method: PASSIVE
                            score: 0.98
                          face_match:
                            score: 0.95
                      - session_id: 038ad62f-5ebd-46c2-afe9-4b2956bf687f
                        session_kind: user
                        session_number: 719
                        session_url: https://verify.didit.me/session/7RGKiO6ioGH6
                        portrait_image: null
                        document_type: null
                        full_name: null
                        country: null
                        status: Not Started
                        vendor_data: your-user-id-124
                        didit_internal_id: eb4e679d-ca4b-461f-9685-687bac29ebdb
                        created_at: '2026-06-09T08:02:23.343053Z'
                        features:
                          - feature: ID_VERIFICATION
                            status: Not Finished
                          - feature: LIVENESS
                            status: Not Finished
                          - feature: FACE_MATCH
                            status: Not Finished
                          - feature: AML
                            status: Not Finished
                          - feature: IP_ANALYSIS
                            status: Not Finished
                        phone_number: null
                        email_address: null
                        additional_details: null
                Mixed KYC + KYB (session_kind=all):
                  summary: session_kind=all - 一行 KYC 紧跟一行 KYB
                  value:
                    count: 2
                    next: null
                    previous: null
                    results:
                      - session_id: 5b3720ed-d429-42ef-b67f-37ea805f48ee
                        session_kind: user
                        session_number: 720
                        session_url: https://verify.didit.me/session/CuXoBYCYVO5Y
                        portrait_image: null
                        document_type: Identity Card
                        full_name: Jane Marie Doe
                        country: ESP
                        status: In Review
                        vendor_data: your-user-id-123
                        didit_internal_id: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147
                        created_at: '2026-06-09T12:26:54.328364Z'
                        features:
                          - feature: ID_VERIFICATION
                            status: In Review
                          - feature: LIVENESS
                            status: Approved
                        phone_number: null
                        email_address: null
                        additional_details:
                          liveness:
                            method: PASSIVE
                            score: 0.98
                      - session_id: 8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52
                        session_kind: business
                        session_number: 42
                        status: Approved
                        vendor_data: your-company-id-77
                        created_at: '2026-06-08T09:14:02.118450Z'
                        workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab
                        workflow_type: kyb
                        workflow_label: Standard KYB
                        company_name: Acme Holdings S.L.
                        registration_number: B12345678
                        country: ES
        '301':
          description: >-
            重定向到规范的带尾随斜杠 URL。当请求路径为 `/v3/sessions`（无尾随斜杠）时返回；`Location`
            请求头指向保留查询字符串的 `/v3/sessions/`。GET 客户端通常会自动跟随重定向。
        '400':
          description: 无效的查询参数。响应体是一个以违规参数为键的对象。
          content:
            application/json:
              examples:
                Invalid session_kind:
                  summary: session_kind 不是 user/business/all 之一
                  value:
                    session_kind: Must be "user", "business", or "all".
                Invalid date:
                  summary: date_from/date_to 格式错误
                  value:
                    date_from:
                      - Enter a valid date.
                Invalid didit_internal_id:
                  summary: didit_internal_id 不是有效的 UUID
                  value:
                    didit_internal_id:
                      - Enter a valid UUID.
                Invalid api_service:
                  summary: api_service 不在允许的选项中
                  value:
                    api_service:
                      - >-
                        Select a valid choice. FOO is not one of the available
                        choices.
        '403':
          description: >-
            缺少、格式错误或已撤销的 API 密钥。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。


            **已删除的应用：**在应用被删除后的几分钟内，使用其 API 密钥之一发出的请求可能会返回 `{"detail": "This
            application was deleted.", "code":
            "application_deleted"}`。请勿重试：该应用及其 API
            密钥已不再存在。这几分钟过后，该密钥将像任何其他无效密钥一样被拒绝。
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: You do not have permission to perform this action.
                  code:
                    type: string
                    description: 机器可读的原因，仅在某些失败情况下出现。`application_deleted`：API 密钥属于已被删除的应用。
                    example: application_deleted
                required:
                  - detail
              examples:
                Forbidden:
                  summary: x-api-key 缺失或无效
                  value:
                    detail: You do not have permission to perform this action.
                ApplicationDeleted:
                  summary: 已删除应用的 API 密钥
                  value:
                    detail: This application was deleted.
                    code: application_deleted
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl -s
            'https://verification.didit.me/v3/sessions/?status=Approved,In%20Review&date_from=2026-06-01&limit=20'
            \
              -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.sessions.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.sessions.list()) {
              console.log(item);
            }
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListAutoPaging(ctx, didit.SessionsListParams{})\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.sessions().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->sessions->list() as $item) {
                print_r($item);
            }
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            didit.sessions.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.Sessions.ListAsync())
            {
                Console.WriteLine(JsonSerializer.Serialize(item));
            }
components:
  schemas:
    UserSessionListItem:
      title: 'KYC session row (session_kind: user)'
      type: object
      description: >-
        用户验证（KYC）会话的摘要行。身份字段（`full_name`、`country`、`document_type`、`portrait_image`、联系人字段）随着用户完成验证步骤逐步填充，在相关步骤完成之前为
        `null`。受工作流响应属性配置限制的字段也返回为 `null`。
      required:
        - session_id
        - session_kind
        - session_number
        - session_url
        - portrait_image
        - document_type
        - full_name
        - country
        - status
        - vendor_data
        - didit_internal_id
        - created_at
        - features
        - phone_number
        - email_address
        - additional_details
      properties:
        session_id:
          type: string
          format: uuid
          description: >-
            验证会话的唯一标识符。与 `GET /v3/session/{sessionId}/decision/` 一起使用以获取完整的决策
            payload。
          example: 5b3720ed-d429-42ef-b67f-37ea805f48ee
        session_kind:
          type: string
          enum:
            - user
          description: 行区分符。对于 KYC 行始终为 `"user"`；企业验证（KYB）行的值为 `"business"` 且具有不同的结构。
          example: user
        session_number:
          type: integer
          description: 您应用内该会话便于人类阅读的序号。也可通过 `search` 参数进行匹配。
          example: 720
        session_url:
          type: string
          nullable: true
          description: 终端用户打开以完成流程的托管验证 URL。当会话没有托管 URL 时为 `null`。
          example: https://verify.didit.me/session/CuXoBYCYVO5Y
        portrait_image:
          type: string
          nullable: true
          description: >-
            最佳可用肖像照的会过期的（预签名）URL：如可用则为 NFC
            芯片照片，否则为身份证件肖像照，再否则为活体检测参考图像。在其中任一项存在之前为 `null`。请及时下载；链接会过期。
          example: >-
            https://<media-host>/portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=...
        document_type:
          type: string
          nullable: true
          enum:
            - Passport
            - Identity Card
            - Driver's License
            - Residence Permit
            - Health Insurance Card
            - Tax Card
          description: >-
            易于阅读的已验证身份证件类型。证件验证完成前为
            `null`，且当验证后的代码没有显示映射（`SSC`、`WP`、`VISA`、`PSC`、`BC`、`OTHER`）时，完成后也为
            `null`。注意：`document_type`
            查询参数通过短代码（`P`、`ID`、`DL`、`RP`、...）进行过滤，而非这些显示值。
          example: Passport
        full_name:
          type: string
          nullable: true
          description: >-
            会话可用的最佳姓名，按以下顺序解析：身份证件 OCR、AML
            筛查数据、数据库核验筛查数据、地址证明文件，然后是创建会话时提供的预期详情。尚无可用的数据时为 `null`。
          example: Jane Marie Doe
        country:
          type: string
          nullable: true
          description: >-
            与会话关联的 ISO 3166-1 alpha-3
            国家/地区代码，按以下顺序解析：身份证件签发国/地区、数据库核验签发国/地区、地址证明签发国/地区、预期详情，然后是已验证电话的国家/地区。可能与国籍不同。
          example: ESP
        status:
          type: string
          enum:
            - Not Started
            - In Progress
            - Approved
            - Declined
            - In Review
            - Expired
            - Abandoned
            - Kyc Expired
            - Resubmitted
            - Awaiting User
          description: 总体会话状态。生命周期请参阅[验证状态](/zh/integration/verification-statuses)页面。
          example: Approved
        vendor_data:
          type: string
          nullable: true
          description: 您为终端用户指定的自身标识符，将完全按照创建会话时发送的内容原样返回。
          example: your-user-id-123
        didit_internal_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            此会话背后已验证用户个人资料的 Didit 内部标识符。同一用户的多个会话之间保持稳定；可通过 `didit_internal_id`
            查询参数进行过滤。
          example: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147
        created_at:
          type: string
          format: date-time
          description: 创建会话时的 UTC 时间戳。
          example: '2026-06-09T12:26:54.328364Z'
        features:
          type: array
          description: 会话工作流中配置的每个验证步骤的功能状态，按工作流顺序排列。
          items:
            type: object
            required:
              - feature
              - status
            properties:
              feature:
                type: string
                enum:
                  - ID_VERIFICATION
                  - NFC
                  - LIVENESS
                  - FACE_MATCH
                  - POA
                  - QUESTIONNAIRE
                  - EMAIL_VERIFICATION
                  - PHONE
                  - AML
                  - IP_ANALYSIS
                  - AGE_ESTIMATION
                  - DATABASE_VALIDATION
                  - GEOLOCATION
                description: 验证功能标识符。
                example: ID_VERIFICATION
              status:
                type: string
                enum:
                  - Not Finished
                  - Approved
                  - Declined
                  - In Review
                  - Resub Requested
                description: 此功能的状态。在步骤完成前为 `Not Finished`。
                example: Approved
        phone_number:
          type: object
          nullable: true
          description: 与会话关联的电话号码：如果执行了电话验证，则为验证后的电话号码，否则为会话创建时提供的联系电话。如果两者均不存在，则为 `null`。
          required:
            - number
            - is_verified
          properties:
            number:
              type: string
              description: E.164 格式的电话号码。
              example: '+14155552671'
            is_verified:
              type: boolean
              description: 仅当电话验证功能通过此号码时为 `true`。
              example: true
        email_address:
          type: object
          nullable: true
          description: 与会话关联的邮箱：执行过邮箱验证时为已验证的邮箱，否则为创建会话时提供的联系邮箱。两者均不存在时为 `null`。
          required:
            - email
            - is_verified
          properties:
            email:
              type: string
              format: email
              example: jane@example.com
            is_verified:
              type: boolean
              description: 仅当邮箱验证功能通过此地址时为 `true`。
              example: true
        additional_details:
          type: object
          nullable: true
          description: 紧凑的各功能附加信息。仅产生数据的功能会作为键显示；若无功能产生附加信息则为 `null`。被工作流响应属性配置排除的字段将被省略。
          properties:
            aml:
              type: object
              description: 在运行 AML 筛查时存在。
              properties:
                total_hits:
                  type: integer
                  description: AML 筛查命中项数量。
                  example: 0
                entity_type:
                  type: string
                  description: 受筛查实体类型。
                  example: person
                is_adverse_media_fetched:
                  type: boolean
                  example: false
                screened_data:
                  type: object
                  description: 已筛查数据的子集。仅包含非空键。
                  properties:
                    nationality:
                      type: string
                      example: ESP
                    document_number:
                      type: string
                      example: XX1234567
                    date_of_birth:
                      type: string
                      example: '1990-05-21'
            database_validation:
              type: object
              description: 在运行数据库核验时存在。
              properties:
                validation_type:
                  type: string
                  example: DOCUMENT_VALIDATION
                match_type:
                  type: string
                  example: FULL_MATCH
                identification_number:
                  type: string
                  description: 已核验的税号、个人识别号或证件号码（首个可用值）。
                  example: 12345678Z
            poa:
              type: object
              description: 在运行地址证明时存在。
              properties:
                document_type:
                  type: string
                  example: UTILITY_BILL
                issuer:
                  type: string
                  example: Energy Co
                address:
                  type: string
                  example: Calle Mayor 1, 28013 Madrid
                name_on_document:
                  type: string
                  example: Jane Marie Doe
            liveness:
              type: object
              description: 在运行活体检测时存在。
              properties:
                method:
                  type: string
                  example: PASSIVE
                score:
                  type: number
                  description: 活体置信度分数，保留两位小数。
                  example: 0.98
            face_match:
              type: object
              description: 在运行人脸比对时存在。
              properties:
                score:
                  type: number
                  description: 人脸比对相似度分数，四舍五入保留 2 位小数。
                  example: 0.95
                source_image:
                  type: string
                  description: 源人脸图像的会过期的（预签名）URL。
                  example: https://<media-host>/faces/source.jpg?X-Amz-Expires=3600&...
                target_image:
                  type: string
                  description: 目标人脸图像的会过期的（预签名）URL。
                  example: https://<media-host>/faces/target.jpg?X-Amz-Expires=3600&...
            phone_verification:
              type: object
              description: 在运行电话验证时存在。
              properties:
                country_code:
                  type: string
                  description: 电话号码所在国家/地区的 ISO 3166-1 alpha-2 代码。
                  example: US
                is_temporary:
                  type: boolean
                  example: false
                is_ported:
                  type: boolean
                  example: false
                is_blocked:
                  type: boolean
                  example: false
            email_verification:
              type: object
              description: 在运行邮箱验证时存在。
              properties:
                is_breached:
                  type: boolean
                  example: false
                is_disposable:
                  type: boolean
                  example: false
                is_undeliverable:
                  type: boolean
                  example: false
                is_blocklisted:
                  type: boolean
                  example: false
        assignee:
          type: object
          nullable: true
          description: 会话所分配到的控制台审核员，未分配给任何人时为 `null`。
          properties:
            email:
              type: string
              format: email
            assigned_at:
              type: string
              format: date-time
              nullable: true
        waiting_since:
          type: string
          format: date-time
          nullable: true
          description: 会话开始等待审核的时间。除非会话为 `In Review`，否则为 `null`。
        sla_due_at:
          type: string
          format: date-time
          nullable: true
          description: 审核截止时间，依据在控制台中为您的应用设置的审核截止期限。除非会话为 `In Review` 且设置了截止期限，否则为 `null`。
        top_warnings:
          type: array
          description: 会话中最重要的最多几条警告，用于快速初筛视图。完整列表见决策。
          items:
            type: object
            properties:
              risk:
                type: string
                description: 警告代码，例如 `FACE_MATCH_LOW_SIMILARITY`。
              feature:
                type: string
                description: 触发该项的功能。
              log_type:
                type: string
                nullable: true
                description: '`error` 或 `warning`；遗留条目为 `null`。'
              short_description:
                type: string
        warnings_count:
          type: integer
          description: 会话中的警告数量。
    BusinessSessionListItem:
      title: 'KYB session row (session_kind: business)'
      type: object
      description: 企业验证（KYB）会话的摘要行。仅在 `session_kind` 为 `business` 或 `all` 时返回。
      required:
        - session_id
        - session_kind
        - session_number
        - status
        - vendor_data
        - created_at
        - workflow_id
        - workflow_type
        - workflow_label
        - company_name
        - registration_number
        - country
      properties:
        session_id:
          type: string
          format: uuid
          description: 企业验证会话的唯一标识符。
          example: 8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52
        session_kind:
          type: string
          enum:
            - business
          description: 行区分符。对于 KYB 行始终为 `"business"`。
          example: business
        session_number:
          type: integer
          description: 您应用内该企业会话便于人类阅读的序号。独立于 KYC 会话进行编号。
          example: 42
        status:
          type: string
          enum:
            - Not Started
            - In Progress
            - Approved
            - Declined
            - In Review
            - Expired
            - Abandoned
            - Kyc Expired
            - Resubmitted
            - Awaiting User
          description: 总体会话状态。请参阅[验证状态](/zh/integration/verification-statuses)页面。
          example: Approved
        vendor_data:
          type: string
          nullable: true
          description: 您为企业指定的自身标识符，将完全按照创建会话时发送的内容原样返回。
          example: your-company-id-77
        created_at:
          type: string
          format: date-time
          description: 创建会话时的 UTC 时间戳。
          example: '2026-06-08T09:14:02.118450Z'
        workflow_id:
          type: string
          format: uuid
          nullable: true
          description: 创建此会话所使用工作流的标识符。
          example: 9f9b1234-aaaa-bbbb-cccc-1234567890ab
        workflow_type:
          type: string
          nullable: true
          description: 工作流类型。企业工作流为 `kyb`。
          example: kyb
        workflow_label:
          type: string
          nullable: true
          description: 工作流的显示名称。
          example: Standard KYB
        company_name:
          type: string
          nullable: true
          description: 正在验证的企业名称，来源于与该会话关联的登记机构企业。在选择企业之前为 `null`。
          example: Acme Holdings S.L.
        registration_number:
          type: string
          nullable: true
          description: 与会话关联的登记公司的企业注册号。
          example: B12345678
        country:
          type: string
          nullable: true
          description: 与会话关联的登记公司的国家/地区代码。
          example: ES
  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.