> ## 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 的 POST /v3/email/check/ 接口可校验一次性邮箱验证码，并返回数据泄露、临时邮箱与送达性信号。按量付费，无需签订合同。

## 增值功能

将 `enable_enrichment` 设置为 `true`，即可同时对该邮箱地址进行邮箱情报分析，包括风险评分和泄露历史。
该附加功能按标准价格每次请求收取 \$0.05，并在验证本身的价格之外另行计费。
当余额不足以支付该费用时，请求将返回 `403`。

有三个字段决定信号的处理方式。
每个字段的取值为 `NO_ACTION`（默认值）或 `DECLINE`，并且只有在 `enable_enrichment` 为 `true` 时才会生效。

| 字段 | 拒绝条件 |
| - | - |
| `email_intelligence_score_action` | 风险评分高于阈值。 |
| `recent_email_breach_action` | 该邮箱地址出现在近期已知的数据泄露事件中。 |
| `frequent_email_breach_action` | 该邮箱地址出现在多次已知的数据泄露事件中。 |

设置为 `NO_ACTION` 时，信号仍会在 `email.email_intelligence` 中返回，便于您应用自己的规则。


## OpenAPI

````yaml zh/openapi-25.json POST /v3/email/check/
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/email/check/:
    post:
      tags:
        - Standalone APIs
      summary: 核验邮箱验证码
      description: >-
        验证通过 [`POST /v3/email/send/`](/zh/standalone-apis/email-send) 投递的
        OTP，并获取最终验证结果以及邮箱情报：可投递性、数据泄露暴露情况（来自泄露情报数据库的 `is_breached` 及 `breaches`
        列表）、一次性邮箱提供商检测，以及该地址在您各会话间的重复使用情况。


        **检查如何查找验证记录。** 匹配依据为您的应用加上 `email` 地址，`request_id` 不是输入参数。系统会检查过去 **5
        分钟**内创建的最新待处理验证。如果不存在（从未发送、已完成、发送时不可投递或早于 5 分钟），该 endpoint 返回 `200`，且
        `status: "Expired or Not Found"`。


        **尝试次数预算。** 每次验证允许 **3 次验证码尝试**。前两次输入错误验证码返回 `status:
        "Failed"`，包含剩余尝试次数且 `email: null`；第三次输入错误验证码会将验证最终定性为 `Declined`，附带
        `EMAIL_CODE_ATTEMPTS_EXCEEDED` 警告并返回完整的邮箱报告。验证码比较不区分大小写（适用于
        `alphanumeric_code` 发送方式）；仅最新发送的验证码有效。


        **结果。** `Approved`：验证码正确且未触发拒绝风险。`Declined`（最终状态）：验证码正确但匹配到了拒绝风险（下方的
        `DECLINE`
        操作、黑名单地址，或在完成验证时发现地址不可投递），或尝试次数已耗尽。`Failed`：验证码错误，仍有剩余尝试次数。`Expired or
        Not Found`：无可检查内容。在 `Approved`/`Declined` 状态下，`request_id` 等于发送时的
        `request_id`（会话 ID），且 `email`
        携带完整报告（`is_breached`、`breaches`、`is_disposable`、`is_undeliverable`、`warnings`、`lifecycle`、`matches`）；在
        `Failed` 和 `Expired or Not Found` 状态下，`request_id` 为一次性随机 UUID。


        **风险操作。** `duplicated_email_action`、`breached_email_action` 和
        `disposable_email_action` 决定在验证码正确但检测到相应风险时的处理方式：`DECLINE` 会将最终状态更改为
        `Declined`；`NO_ACTION`（默认）仅在 `email.warnings` 中记录该风险，不影响最终状态。


        **计费。** 核验免费，成功的发送操作已扣除额度。


        **会话持久化。** 最终完成的核验会更新由发送操作创建的会话（在 Business Console 中可见，可通过 `GET
        /v3/session/{sessionId}/decision/` 查询），并触发 `status.updated` Webhook。


        **沙盒。** 沙盒 API 密钥跳过所有处理流程：任何格式正确的验证码（包括 `123456`）均返回包含简化 `email`
        对象（`status`、`email`、`is_breached`、`is_disposable`、`is_undeliverable`）的静态
        `Approved` payload；格式错误的输入仍返回 `400`。不会持久化任何数据。


        **认证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。凭证缺失或无效返回 `403`（`{"detail": "You
        do not have permission to perform this action."}`），此 API 从不返回 `401`。


        **速率限制。** 每个 API 密钥在所有 POST/PATCH/DELETE endpoint 间共享 300
        次请求/分钟的写入预算；超出将返回 `429`。


        **社交足迹。** 将 `enable_social` 设置为 `true` 可添加 `email_social`
        区块：该地址注册的在线平台，包含各分类计数以及任何可用的个人资料详情。`profiles_registered: 0`
        表示已检查相关平台且未发现该地址注册，这是有效且计费的响应。当未请求该附加功能或核验无法完成时，该区块不存在，且在这种情况下不予计费。计费时将在该
        endpoint 本身价格的基础上，按每次请求额外增加一个 `email_social` 计费单位。
      operationId: post_v3email_check
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: >-
                    与匹配的 [`POST
                    /v3/email/send/`](/zh/standalone-apis/email-send)
                    调用中使用的相同邮箱地址。这是将核验与发送关联起来的依据。
                  example: alice@example.com
                code:
                  type: string
                  maxLength: 10
                  description: >-
                    终端用户收到的一次性验证码：4–8 位数字，若发送时使用了 `alphanumeric_code: true`，则为
                    4–8 位字母/数字。比对不区分大小写。
                  example: '123456'
                duplicated_email_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    当您应用的另一位用户（不同的
                    `vendor_data`）已经使用过相同地址并已通过验证（仅计入先前已通过的验证）时采取的操作。`DECLINE`
                    会将最终的 `status` 变为 `Declined`；`NO_ACTION` 会在 `email.warnings`
                    中记录该风险并填充 `email.matches`。
                breached_email_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    当地址出现在已知数据泄露事件中（`email.is_breached`）时的处理操作。`DECLINE` 会将最终
                    `status` 变为 `Declined`；`NO_ACTION` 会在 `email.warnings`
                    中记录该风险。
                disposable_email_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    当域名属于一次性/临时邮箱提供商（`email.is_disposable`）时采取的操作。`DECLINE`
                    会将最终的 `status` 变为 `Declined`；`NO_ACTION` 会在 `email.warnings`
                    中记录该风险。
                enable_enrichment:
                  type: boolean
                  default: false
                  description: >-
                    为 `true` 时，还会对该地址运行邮箱情报分析：风险评分及其数据泄露历史。除此 endpoint
                    本身的价格外，每次请求按单次 `email_intelligence_api` 计费（标价为
                    $0.05）。当您的余额不足以支付时，请求将返回 `403`。
                  example: false
                email_intelligence_score_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    邮箱情报风险评分高于阈值时的操作。`DECLINE` 会将最终 `status` 翻转为
                    `Declined`；`NO_ACTION` 会记录该信号而不拒绝。仅在 `enable_enrichment` 为
                    `true` 时生效。
                recent_email_breach_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    当该地址出现在近期已知的数据泄露事件中时采取的操作。`DECLINE` 会将最终 `status` 更改为
                    `Declined`；`NO_ACTION` 仅记录该信号而不拒绝。仅在 `enable_enrichment` 为
                    `true` 时生效。
                frequent_email_breach_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    当该地址出现在多起已知的数据泄露事件中时采取的操作。`DECLINE` 会将最终 `status` 更改为
                    `Declined`；`NO_ACTION` 仅记录该信号而不拒绝。仅在 `enable_enrichment` 为
                    `true` 时生效。
                enable_social:
                  type: boolean
                  default: false
                  description: >-
                    为 true 时，还会查找该地址的社交足迹，即其注册所在的邮箱、社交、职业、电子商务和娱乐平台。除此 endpoint
                    本身的价格外，每次请求按一个 `email_social` 单位计费。
                  example: true
                email_no_social_presence_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    社交足迹核查发现该地址在其覆盖的所有平台上均未注册时的操作。此 endpoint 仅接受 NO_ACTION 和
                    DECLINE；同名工作流配置键上提供 REVIEW。
              required:
                - email
                - code
            examples:
              Default:
                summary: 记录任何风险但绝不自动拒绝
                value:
                  email: alice@example.com
                  code: '123456'
              Strict risk policy:
                summary: 自动拒绝一次性邮箱和泄露邮箱
                value:
                  email: alice@example.com
                  code: '123456'
                  disposable_email_action: DECLINE
                  breached_email_action: DECLINE
      responses:
        '200':
          description: >-
            核验已完成：错误的验证码和缺失的验证也会返回 `200`；请检查 `status`，而非 HTTP 状态码。`email`
            仅在最终结果（`Approved`/`Declined`）中填充，在 `Failed` 时为 `null`，在 `Expired or
            Not Found` 时不存在。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailVerificationCheckResponse'
              examples:
                Approved:
                  summary: 验证码正确：干净的地址，完整的邮箱报告
                  value:
                    request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24
                    status: Approved
                    message: The verification code is correct.
                    email:
                      status: Approved
                      email: alice@example.com
                      is_breached: false
                      breaches: []
                      is_disposable: false
                      is_undeliverable: false
                      verification_attempts: 1
                      verified_at: '2026-06-12T01:24:47.311323Z'
                      warnings: []
                      lifecycle:
                        - type: EMAIL_VERIFICATION_MESSAGE_SENT
                          timestamp: '2026-06-12T01:23:39.580554+00:00'
                          details:
                            status: Success
                            reason: null
                          fee: 0.02
                        - type: VALID_CODE_ENTERED
                          timestamp: '2026-06-12T01:24:47.311201+00:00'
                          details:
                            code_tried: '123456'
                            status: Approved
                          fee: 0
                        - type: EMAIL_VERIFICATION_APPROVED
                          timestamp: '2026-06-12T01:24:47.384292+00:00'
                          details: null
                          fee: 0
                      matches: []
                    vendor_data: user-1234
                    metadata: null
                    created_at: '2026-06-12T01:24:47.401719+00:00'
                Approved with breach exposure:
                  summary: 验证码正确；数据泄露风险记录为警告（breached_email_action=NO_ACTION）
                  value:
                    request_id: 3a1f2b6c-9d4e-4f7a-8b2c-1e5d6f7a8b9c
                    status: Approved
                    message: The verification code is correct.
                    email:
                      status: Approved
                      email: bob@example.com
                      is_breached: true
                      breaches:
                        - name: ExampleApp
                          domain: exampleapp.com
                          breach_date: '2019-03-21'
                          breach_emails_count: 763117
                          description: >-
                            In March 2019, the social platform ExampleApp
                            suffered a data breach that exposed email addresses
                            and passwords.
                          logo_path: https://<media-host>/logos/ExampleApp.png
                          data_classes:
                            - email_addresses
                            - passwords
                          is_verified: true
                      is_disposable: false
                      is_undeliverable: false
                      verification_attempts: 1
                      verified_at: '2026-06-12T01:24:47.311323Z'
                      warnings:
                        - feature: EMAIL
                          risk: BREACHED_EMAIL_DETECTED
                          additional_data: null
                          log_type: information
                          short_description: Breached email detected
                          long_description: >-
                            This email address was found in one or more known
                            data breaches.
                      lifecycle:
                        - type: EMAIL_VERIFICATION_MESSAGE_SENT
                          timestamp: '2026-06-12T01:23:39.580554+00:00'
                          details:
                            status: Success
                            reason: null
                          fee: 0.02
                        - type: VALID_CODE_ENTERED
                          timestamp: '2026-06-12T01:24:47.311201+00:00'
                          details:
                            code_tried: '835126'
                            status: Approved
                          fee: 0
                        - type: EMAIL_VERIFICATION_APPROVED
                          timestamp: '2026-06-12T01:24:47.384292+00:00'
                          details: null
                          fee: 0
                      matches: []
                    vendor_data: user-5678
                    metadata: null
                    created_at: '2026-06-12T01:24:47.401719+00:00'
                Failed (attempts remaining):
                  summary: 验证码错误，用户可以重试；此处的 request_id 为一次性 UUID
                  value:
                    request_id: 11111111-2222-3333-4444-555555555555
                    status: Failed
                    message: 'The verification code is incorrect. Attempts remaining: 2'
                    email: null
                    vendor_data: user-1234
                    metadata: null
                    created_at: '2026-06-12T01:24:21.512340+00:00'
                Declined (risk policy):
                  summary: 验证码正确，但地址是一次性邮箱且 disposable_email_action=DECLINE
                  value:
                    request_id: 8c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f
                    status: Declined
                    message: The verification code is correct.
                    email:
                      status: Declined
                      email: tempuser42@mailinator.com
                      is_breached: false
                      breaches: []
                      is_disposable: true
                      is_undeliverable: false
                      verification_attempts: 1
                      verified_at: '2026-06-12T01:24:47.311323Z'
                      warnings:
                        - feature: EMAIL
                          risk: DISPOSABLE_EMAIL_DETECTED
                          additional_data: null
                          log_type: error
                          short_description: Disposable email detected
                          long_description: >-
                            The system detected that the email is disposable,
                            which is not allowed.
                      lifecycle:
                        - type: EMAIL_VERIFICATION_MESSAGE_SENT
                          timestamp: '2026-06-12T01:23:39.580554+00:00'
                          details:
                            status: Success
                            reason: null
                          fee: 0.02
                        - type: VALID_CODE_ENTERED
                          timestamp: '2026-06-12T01:24:47.311201+00:00'
                          details:
                            code_tried: '123456'
                            status: Approved
                          fee: 0
                        - type: EMAIL_VERIFICATION_DECLINED
                          timestamp: '2026-06-12T01:24:47.384292+00:00'
                          details:
                            reason: DISPOSABLE_EMAIL_DETECTED
                          fee: 0
                      matches: []
                    vendor_data: user-1234
                    metadata: null
                    created_at: '2026-06-12T01:24:47.401719+00:00'
                Expired or Not Found:
                  summary: 过去 5 分钟内该地址没有待处理的验证
                  value:
                    request_id: 88808a77-06e9-4cb0-85f5-9c052ddfd987
                    status: Expired or Not Found
                    message: No pending email verification found in the last 5 minutes.
                    vendor_data: null
                    metadata: null
                    created_at: '2026-06-12T01:24:59.887904+00:00'
        '400':
          description: 验证错误 — DRF 的字段错误包装格式：每个违规字段对应一个消息数组。
          content:
            application/json:
              examples:
                Invalid email:
                  summary: 邮箱地址格式错误
                  value:
                    email:
                      - Enter a valid email address.
                Missing code:
                  summary: 请求体中未包含 `code`
                  value:
                    code:
                      - This field is required.
        '403':
          description: >-
            权限被拒绝。当缺少 `x-api-key` 请求头时返回；错误、已撤销或已过期的密钥返回
            `401`。核验是免费的，因此此处不进行额度检查。
          content:
            application/json:
              examples:
                Missing or invalid API key:
                  summary: 缺少 `x-api-key` 请求头，或者密钥无效/已被吊销
                  value:
                    detail: You do not have permission to perform this action.
        '429':
          description: >-
            超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300
            次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含
            `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和
            `Retry-After` 响应头。
          content:
            application/json:
              examples:
                Write rate limit exceeded:
                  summary: 当前分钟内的写入请求超过 300 次
                  value:
                    detail: >-
                      Write request rate limit exceeded. You can make up to 300
                      requests per minute.
              schema:
                type: object
                properties:
                  detail:
                    type: string
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/email/check/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "email": "alice@example.com",
                "code": "123456",
                "disposable_email_action": "DECLINE"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.email.check_code(
                email="alice@example.com",
                code="123456",
            )
            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.email.checkCode({
              email: "alice@example.com",
              code: "123456",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.CheckCode(ctx, didit.EmailCheckCodeParams{\n\tEmail: \"alice@example.com\",\n\tCode:  \"123456\",\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.EmailCheckCodeParams;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.email().checkCode(EmailCheckCodeParams.builder()
                    .email("alice@example.com")
                    .code("123456")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->email->checkCode([
                'email' => 'alice@example.com',
                'code' => '123456',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.email.check_code(
              email: "alice@example.com",
              code: "123456"
            )
            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.Email.CheckCodeAsync(new
            EmailCheckCodeParams

            {
                Email = "alice@example.com",
                Code = "123456",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    EmailVerificationCheckResponse:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            状态为 `Approved`/`Declined` 时：匹配验证的会话 ID，与 `POST /v3/email/send/` 返回的
            `request_id` 相同。状态为 `Failed` 和 `Expired or Not Found` 时：一个随机的一次性
            UUID，后续无法查询。
        status:
          type: string
          enum:
            - Approved
            - Declined
            - Failed
            - Expired or Not Found
          description: >-
            `Approved` — 验证码正确，无拒绝风险。`Declined` —
            最终状态：匹配到拒绝风险或尝试次数上限（3）已用尽。`Failed` — 验证码错误，仍有剩余尝试次数。`Expired or Not
            Found` — 在过去 5 分钟内该地址没有待处理的验证。
        message:
          type: string
          description: 结果的便于人类阅读的说明，包括输入错误验证码后的剩余尝试次数。
        email:
          type: object
          nullable: true
          description: >-
            完整邮箱报告。仅在已完成的结果（`Approved`/`Declined`）中存在（非 null）；在 `Failed` 时为
            `null`，在 `Expired or Not Found` 时不存在。
          properties:
            status:
              type: string
              enum:
                - Approved
                - Declined
                - In Review
                - Not Finished
                - Expired
              description: 邮箱验证的最终状态。对于已完成的检查，与顶级 `status` 一致。
            email:
              type: string
              format: email
              description: 已验证的邮箱地址。
              example: alice@example.com
            is_breached:
              type: boolean
              description: 当该地址出现在已知数据泄露事件中时为 `true`（在最终确认时运行泄露情报查询）。
            breaches:
              type: array
              description: 包含此地址的最多 5 次最近已知数据泄露事件。当 `is_breached` 为 `false` 时为空数组（或省略）。
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: 数据泄露标识符。
                  domain:
                    type: string
                    description: 发生泄露的服务的域名。
                  breach_date:
                    type: string
                    format: date
                    description: 违规行为发生的日期。
                  breach_emails_count:
                    type: integer
                    description: 泄露事件中暴露的账户总数。
                  description:
                    type: string
                    description: 便于人类阅读的泄露事件描述（可能包含 HTML 标记）。
                  logo_path:
                    type: string
                    description: 发生数据泄露的服务徽标 URL。
                  data_classes:
                    type: array
                    items:
                      type: string
                    description: >-
                      泄露的数据类别，采用 snake_case 格式（例如
                      `email_addresses`、`passwords`）。
                  is_verified:
                    type: boolean
                    description: 该泄露事件是否已被核实为真实存在。
            is_disposable:
              type: boolean
              description: 当域名属于已知的临时/一次性邮箱服务商时为 `true`。
            is_undeliverable:
              type: boolean
              description: 当该地址无法接收邮件（语法或 DNS/MX 验证失败，或邮件被退回）时为 `true`。
            verification_attempts:
              type: integer
              description: 此验证发送 OTP 的次数（1 次，重试后为 2 次）。
            verified_at:
              type: string
              format: date-time
              nullable: true
              description: 输入正确代码的时间。如果验证从未通过，则为 `null`。
            warnings:
              type: array
              description: 验证期间记录的风险警告（重复、泄露、一次性、无法投递、超出尝试次数、黑名单等）。无任何警告时为空数组。
              items:
                type: object
                properties:
                  feature:
                    type: string
                    description: 产生该警告的功能。在此处始终为 `EMAIL`。
                  risk:
                    type: string
                    description: 机器可读的风险代码。
                  additional_data:
                    type: object
                    nullable: true
                    description: 特定风险的上下文（例如重复风险对应的重复会话 id）。当风险不包含额外数据时为 `null`。
                  log_type:
                    type: string
                    enum:
                      - error
                      - warning
                      - information
                    description: >-
                      严重程度。`error` 级别的风险会导致验证被拒绝，`warning`
                      会将其标记为待审核，`information` 仅作记录而不影响状态。
                  short_description:
                    type: string
                    description: 易于阅读的单行风险摘要。
                  long_description:
                    type: string
                    description: 风险的便于人类阅读的说明。
            lifecycle:
              type: array
              description: >-
                验证的时间顺序审计记录。事件 `type`
                为以下之一：`EMAIL_VERIFICATION_MESSAGE_SENT`、`EMAIL_VERIFICATION_RETRY_MESSAGE_SENT`、`VALID_CODE_ENTERED`、`INVALID_CODE_ENTERED`、`EMAIL_VERIFICATION_APPROVED`、`EMAIL_VERIFICATION_DECLINED`、`EMAIL_VERIFICATION_IN_REVIEW`、`EMAIL_VERIFICATION_EXPIRED`。
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: 事件类型。
                  timestamp:
                    type: string
                    format: date-time
                    description: 事件发生的时间。
                  details:
                    type: object
                    nullable: true
                    description: >-
                      特定事件的 payload。发送事件：`{status,
                      reason}`。验证码输入事件：`{code_tried,
                      status}`。最终状态事件：`null`，或在已拒绝或审核中时为 `{reason}`。
                  fee:
                    type: number
                    description: 此事件计费的美元金额。仅在首次成功发送时不为零；对于重试、验证码输入和状态事件为 0。
            matches:
              type: array
              description: >-
                您的应用（KYC、KYB 或 API）中不同用户（不同的 `vendor_data`）使用相同邮箱地址的其他会话。最多 5
                个条目；如果存在基于名单条目的黑名单匹配（且仅当不存在源自会话的黑名单邮箱时），该匹配项会置于开头，源自会话的匹配项保持
                created_at 排序。无匹配项时为空数组。
              items:
                type: object
                properties:
                  session_id:
                    type: string
                    format: uuid
                    description: 使用此邮箱地址的另一个验证的会话 id。
                  session_number:
                    type: integer
                    description: 该会话便于人类阅读的序号。
                  vendor_data:
                    type: string
                    nullable: true
                    description: 该会话的 `vendor_data`。
                  verification_date:
                    type: string
                    description: 该会话的创建时间（`YYYY-MM-DDTHH:MM:SSZ`）。
                  email:
                    type: string
                    description: 匹配的邮箱地址。
                  status:
                    type: string
                    description: 该会话的状态（例如 `Approved`、`Declined`、`In Progress`）。
                  is_blocklisted:
                    type: boolean
                    description: 该邮箱地址是否在您应用的黑名单中。
                  api_service:
                    type: string
                    nullable: true
                    description: >-
                      对于 API 类型的会话，为创建该会话的独立 API（例如
                      `PHONE_VERIFICATION`）；对于常规验证会话为 `null`。
                  source:
                    type: string
                    description: >-
                      发现匹配的位置。通常为 `session`；通过组织名单条目命中的黑名单会在前面附加一个合成的匹配项，其
                      `source: "list_entry"` 且 `session_id`/`session_number` 为
                      null。
            email_social:
              $ref: '#/components/schemas/EmailSocialFootprint'
            email_intelligence:
              allOf:
                - $ref: '#/components/schemas/EmailIntelligence'
              description: 邮箱情报信号。仅在检查中 `enable_enrichment` 为 `true` 时存在。
        vendor_data:
          type: string
          nullable: true
          description: 匹配验证会话的 `vendor_data`。若为 `Expired or Not Found` 则为 `null`。
        metadata:
          type: object
          nullable: true
          description: 匹配验证会话的 `metadata`。在 `Expired or Not Found` 时为 `null`。
        created_at:
          type: string
          format: date-time
          description: 此检查响应的时间戳。
    EmailSocialFootprint:
      type: object
      nullable: true
      description: >-
        邮箱地址的社交足迹：其注册的在线平台。仅当设置了 `enable_social` 且检查完成时才会出现。若未返回对应数据，各计数项可能为
        null。`profiles_registered: 0`
        表示已检查相关平台且未在任何平台上发现该邮箱地址，这是一个有效的计费结果，也是合成身份的常见信号。
      properties:
        profiles_registered:
          type: integer
          nullable: true
          description: 已确认该邮箱地址已注册的平台。
          example: 5
        profiles_checked:
          type: integer
          nullable: true
          description: 已评估注册情况的平台。
          example: 14
        names_found:
          type: integer
          nullable: true
          description: 返回了关联姓名的平台。
          example: 0
        photos_found:
          type: integer
          nullable: true
          description: 返回了个人资料头像的平台。
          example: 0
        communication_breadth:
          type: integer
          nullable: true
          description: 检测到存在活动的通信平台。
          example: 2
        digital_footprint_diversity:
          type: integer
          nullable: true
          description: 检测到存在记录的不同平台类别。
          example: 5
        digital_sophistication_index:
          type: integer
          nullable: true
          description: 综合数字成熟度指标，0-10。
          example: 5
        engagement_depth_index:
          type: integer
          nullable: true
          description: 个人资料丰富度指标，0-10。
          example: 3
        subscription_affordability_index:
          type: integer
          nullable: true
          description: 免费与付费平台混合比例，0-10。
          example: 2
        free_platforms:
          type: integer
          nullable: true
          description: 在免费平台上的注册数。
          example: 4
        full_paid_platforms:
          type: integer
          nullable: true
          description: 在完全付费平台上的注册数。
          example: 0
        partial_paid_platforms:
          type: integer
          nullable: true
          description: 在免费增值平台上的注册数。
          example: 1
        whatsapp_profile_completeness:
          type: string
          nullable: true
          enum:
            - Basic
            - Partial
            - Complete
            - Not Present
            - null
          description: WhatsApp 资料的完整性。仅限电话；邮箱为 null。
          example: Partial
        registered_platforms:
          type: array
          description: 已确认注册的平台。
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        not_registered_platforms:
          type: array
          description: 检查结果为阴性的平台。
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        categories:
          type: object
          description: 每个平台类别的注册数量和比例。
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintCategorySummary'
        profiles:
          type: object
          description: 各平台个人资料详情，以平台为键（在平台公开这些信息时返回）。
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintProfile'
    EmailIntelligence:
      type: object
      description: 归一化的邮箱情报区块。仅在该邮箱运行了情报附加组件时存在；存在时还会以相同值的 `enrichment` 别名提供。
      properties:
        score:
          type: number
          nullable: true
          description: 归一化的 0-100 风险评分。分值越高风险越大。
        deliverable:
          type: string
          nullable: true
          description: 可投递性等级（例如 `high`）。
        breach_risk_level:
          type: string
          nullable: true
          description: '`Low`、`Medium` 或 `High`。'
        breach_risk_index:
          type: number
          nullable: true
          description: 泄露风险数值指数。
        is_recent_breach:
          type: boolean
          nullable: true
          description: 当该地址出现在近期泄露事件中时为 `true`。
        is_frequent_breached:
          type: boolean
          nullable: true
          description: 当该地址出现在多次泄露事件中时为 `true`。
        is_disposable:
          type: boolean
          nullable: true
          description: 当域名属于一次性邮箱服务商时为 `true`。
        is_free_domain:
          type: boolean
          nullable: true
          description: 当域名属于免费邮箱服务商时为 `true`。
        is_breached:
          type: boolean
          nullable: true
          description: 当该地址出现在已知泄露事件中时为 `true`。
        no_of_breaches:
          type: number
          nullable: true
          description: 包含该地址的已知泄露事件数量。
        reason_codes:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: 信号的稳定 Didit 标识符，例如 `IR-5AC67A32`。不透明标识：可据此分组和过滤，请勿解析其内容。
              value:
                nullable: true
                description: >-
                  对于风险标记（例如
                  `voip`、`leaked`、`disposable`、`spam_trap`），为其对应的值：布尔值、等级或日期。对于计分原因代码则为
                  null。
              direction:
                type: string
                enum:
                  - risk
                  - trust
                description: 该信号是增加了风险还是提升了信任度。
              message:
                type: string
                description: 信号的便于人类阅读的说明（英文）。
              impact_level:
                type: string
                nullable: true
                description: 该信号对评分的影响强度，例如 `low`、`medium` 或 `high`。
          description: >-
            解释评分的信号，每个信号包含一个固定的 Didit
            代码、一个方向、一条消息和一个影响级别。新代码可能会随着时间推移而出现，因此请勿拒绝未知代码。
    SocialFootprintPlatform:
      type: object
      properties:
        platform:
          type: string
          description: 平台标识符。
          example: whatsapp
        category:
          type: string
          description: >-
            平台类别，例如
            MESSAGING、SOCIAL_MEDIA、ECOMMERCE、PROFESSIONAL、EMAIL_PROVIDER。
          example: MESSAGING
        scope:
          type: string
          enum:
            - global
            - local
          description: 全球平台为 `global`，特定区域平台为 `local`。
          example: global
    SocialFootprintCategorySummary:
      type: object
      properties:
        registered:
          type: integer
          nullable: true
          description: 该类别中已确认注册的平台。
          example: 2
        ratio:
          type: number
          format: float
          nullable: true
          description: 该类别已检查平台中已注册的比例，0.0-1.0。
          example: 0.6667
    SocialFootprintProfile:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: 个人资料名称（若平台公开）。
        photo:
          type: string
          nullable: true
          description: 个人资料照片 URL（若平台公开）。
        about:
          type: string
          nullable: true
          description: 个人资料简介/生平文本（若平台公开）。
        privacy_status:
          type: string
          nullable: true
          enum:
            - PUBLIC
            - PRIVATE
            - null
          description: 个人资料公开范围（若平台公开）。
        business_account:
          type: boolean
          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.