> ## 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：短信 OTP 验证

> 通过 POST /v3/phone/check/ 核验手机 OTP，同时检测运营商类型、虚拟号码和一次性号码。Didit 提供按量付费，无月度最低消费。

## 处理服务商故障

如果电话服务商暂时不可用，此端点会返回 `502` 以及一个稳定的机器可读代码：

```json theme={null}
{
  "detail": "The phone verification provider is temporarily unavailable.",
  "code": "phone_provider_unavailable"
}
```

请将此响应视为可重试。使用较短的退避时间，并向用户显示服务暂时不可用的提示，而不是要求其更改有效的电话号码或验证码。

## 情报附加功能

将 `enable_enrichment` 设为 `true`，即可同时对该号码运行电话情报分析，包括风险评分、线路类型、号码是否近期携号转网，以及信任指数。
该附加功能按标准价格每次请求收取 \$0.05，另外还需支付电话验证本身的费用。
当你的余额不足以支付该费用时，请求会返回 `403`。

四个字段决定信号的处理方式。
每个字段的取值为 `NO_ACTION`（默认值）或 `DECLINE`，且仅当 `enable_enrichment` 为 `true` 时才生效。

| 字段 | 拒绝条件 |
| - | - |
| `phone_intelligence_score_action` | 风险评分高于阈值。 |
| `phone_type_risk_action` | 号码属于高风险线路类型。 |
| `recent_port_action` | 号码近期已转入其他运营商。 |
| `low_phone_trust_action` | 信任指数等于或低于阈值。 |

当设置为 `NO_ACTION` 时，信号仍会在 `phone.phone_intelligence` 中返回，以便你应用自己的规则。


## OpenAPI

````yaml zh/openapi-25.json POST /v3/phone/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/phone/check/:
    post:
      tags:
        - Standalone APIs
      summary: 核验电话验证码
      description: >-
        验证由 [`POST /v3/phone/send/`](/zh/standalone-apis/phone-send) 发送的
        OTP，并获取最终验证结果以及电话情报：运营商名称和线路类型、虚拟（VoIP）和一次性标记，以及该号码在您所有会话中的重复使用情况。


        **核验如何匹配验证记录。** 匹配依据是您的应用以及 E.164 格式的 `phone_number`，`request_id`
        并非输入参数。系统将检查在过去 **5 分钟**内创建的最新的待处理验证。如果不存在（从未发送、已完成或超过 5 分钟），endpoint
        将返回 `200` 以及 `status: "Expired or Not Found"`。


        **尝试次数配额。** 每次验证允许 **3 次验证码尝试**。前两次输入错误验证码将返回 `status:
        "Failed"`，附带剩余尝试次数且 `phone: null`；第三次输入错误验证码会将验证最终判定为 `Declined`，附带
        `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` 警告，并返回完整的电话报告。


        **结果。** `Approved`：验证码正确且无拒绝风险。`Declined`：终态，验证码正确但匹配到了拒绝风险（下方的
        `DECLINE` 操作、黑名单或高风险号码），或者尝试次数耗尽。`Failed`：验证码错误，尚有剩余尝试次数。`Expired or Not
        Found`：无待核验项。在 `Approved`/`Declined` 状态下，`request_id` 等同于发送时的
        `request_id`（即会话 ID），且 `phone`
        包含完整报告（`carrier`、`is_virtual`、`is_disposable`、`warnings`、`lifecycle`、`matches`）；在
        `Failed` 和 `Expired or Not Found` 状态下，`request_id` 是一个一次性的随机 UUID。


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


        **计费。**
        核验是免费的，投递费用在发送端收取（参见[电话验证定价](/zh/getting-started/phone-verification-pricing)）。


        **会话持久化。** 完成核验后，会更新发送步骤创建的会话（可在 Business Console 中查看，可通过 `GET
        /v3/session/{sessionId}/decision/` 查询），并触发一个 `status.updated` Webhook。


        **沙盒。** 沙盒 API 密钥会跳过所有处理：任何格式合规的验证码（4 到 8 位数字，包括 `123456`）都会返回一个静态的
        `Approved` payload，其中包含简化的扁平 `phone`
        对象（`status`、`phone_number`、`country_code`、`carrier_name`、`line_type`、`flags`）；格式错误的输入仍返回
        `400`。不会持久化任何内容。


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


        **速率限制。** 每个 API 密钥共享每分钟 300 次请求的写入配额，外加上游防滥用的每个号码每小时 4 次尝试上限；超出任一限制均会返回
        `429`。


        **社交足迹。** 将 `enable_social` 设置为 `true` 可添加 `phone_social`
        块：该号码注册的在线平台，包含按类别统计的数量以及所有可用的个人资料详情。`profiles_registered: 0`
        表示已对各平台进行了检查，且未在任何平台上找到该号码，这是一个有效且计费的响应结果。当未请求该附加功能或核验无法完成时，该块不会出现，且在这种情况下不收取费用。计费时，在此
        endpoint 自身价格的基础上，每次请求额外增加一个 `phone_social` 计费单元。
      operationId: post_v3phone_check
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone_number:
                  type: string
                  maxLength: 20
                  description: >-
                    与匹配的 [`POST
                    /v3/phone/send/`](/zh/standalone-apis/phone-send)
                    调用中使用的相同电话号码，采用 E.164 格式。这是将核验与发送关联起来的依据。
                  example: '+14155552671'
                code:
                  type: string
                  minLength: 4
                  maxLength: 8
                  pattern: ^[0-9]{4,8}$
                  description: >-
                    终端用户收到的 OTP。必须为 4–8 位数字，其他任何格式都会返回 `400`
                    且不消耗尝试次数。格式正确但内容错误的验证码会返回 `200` 并附带 `status: "Failed"`，同时消耗
                    3 次尝试机会中的一次。
                  example: '123456'
                duplicated_phone_number_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    当您应用的另一位用户（不同的 `vendor_data`）已经使用过相同号码时采取的操作。`DECLINE` 会将最终的
                    `status` 变为 `Declined`；`NO_ACTION` 会在 `phone.warnings`
                    中记录该风险并填充 `phone.matches`。
                disposable_number_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    当运营商查询将该号码标记为临时/一次性线路（`phone.is_disposable`）时的处理操作。`DECLINE`
                    会将最终 `status` 变为 `Declined`；`NO_ACTION` 会在 `phone.warnings`
                    中记录该风险。
                voip_number_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    当运营商查询报告虚拟线路类型（`voip`、`isp` 或
                    `vpn`，`phone.is_virtual`）时的处理操作。`DECLINE` 会将最终 `status` 变为
                    `Declined`；`NO_ACTION` 会在 `phone.warnings` 中记录该风险。
                enable_enrichment:
                  type: boolean
                  default: false
                  description: >-
                    为 `true` 时，还会对该号码运行电话情报分析：风险评分、线路类型、近期是否携号转网以及信任指数。除此
                    endpoint 本身的价格外，每次请求按单次 `phone_intelligence_api` 计费（标价为
                    $0.05）。当您的余额不足以支付时，请求将返回 `403`。
                  example: false
                phone_intelligence_score_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    电话情报风险评分高于阈值时的操作。`DECLINE` 会将最终 `status` 翻转为
                    `Declined`；`NO_ACTION` 会记录该信号而不拒绝。仅在 `enable_enrichment` 为
                    `true` 时生效。
                phone_type_risk_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    号码属于高风险线路类型时的操作。`DECLINE` 会将最终 `status` 翻转为
                    `Declined`；`NO_ACTION` 会记录该信号而不拒绝。仅在 `enable_enrichment` 为
                    `true` 时生效。
                recent_port_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    号码最近携号转网至另一运营商时的操作。`DECLINE` 会将最终 `status` 翻转为
                    `Declined`；`NO_ACTION` 会记录该信号而不拒绝。仅在 `enable_enrichment` 为
                    `true` 时生效。
                low_phone_trust_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
                    本身的价格外，每次请求按一个 `phone_social` 计费。
                  example: true
                phone_no_social_presence_action:
                  type: string
                  enum:
                    - NO_ACTION
                    - DECLINE
                  default: NO_ACTION
                  description: >-
                    社交足迹核查发现该号码在其覆盖的所有平台上均未注册时的操作。此 endpoint 仅接受 NO_ACTION 和
                    DECLINE；同名工作流配置键上提供 REVIEW。
              required:
                - phone_number
                - code
            examples:
              Default:
                summary: 记录任何风险但绝不自动拒绝
                value:
                  phone_number: '+14155552671'
                  code: '123456'
              Strict risk policy:
                summary: 自动拒绝网络电话（VoIP）和一次性线路
                value:
                  phone_number: '+14155552671'
                  code: '123456'
                  voip_number_action: DECLINE
                  disposable_number_action: DECLINE
      responses:
        '200':
          description: >-
            核验已完成：错误的验证码和缺失的验证也会返回 `200`；请检查 `status`，而非 HTTP 状态码。`phone`
            仅在最终结果（`Approved`/`Declined`）中填充，在 `Failed` 时为 `null`，在 `Expired or
            Not Found` 时不存在。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneVerificationCheckResponse'
              examples:
                Approved:
                  summary: 验证码正确：包含运营商、生命周期及匹配项的完整电话报告
                  value:
                    request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24
                    status: Approved
                    message: The verification code is correct.
                    phone:
                      status: Approved
                      phone_number_prefix: '+1'
                      phone_number: '4155552671'
                      full_number: '+14155552671'
                      country_code: US
                      country_name: United States
                      carrier:
                        name: AT&T
                        type: mobile
                      is_disposable: false
                      is_virtual: false
                      verification_method: whatsapp
                      verification_attempts: 1
                      verified_at: '2026-06-12T01:24:47.311323Z'
                      warnings: []
                      lifecycle:
                        - type: PHONE_VERIFICATION_MESSAGE_SENT
                          timestamp: '2026-06-12T01:23:39.580554+00:00'
                          details:
                            status: Success
                            reason: null
                            channel: whatsapp
                            actual_channel: whatsapp
                          fee: 0.0509
                        - type: PHONE_DELIVERY_DELIVERED
                          timestamp: '2026-06-12T01:23:43.118220+00:00'
                          details:
                            channel: whatsapp
                            status: delivered
                          fee: 0
                        - type: VALID_CODE_ENTERED
                          timestamp: '2026-06-12T01:24:47.311201+00:00'
                          details:
                            code_tried: '123456'
                            status: Approved
                          fee: 0
                        - type: PHONE_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'
                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'
                    phone: null
                    vendor_data: user-1234
                    metadata: null
                    created_at: '2026-06-12T01:24:21.512340+00:00'
                Declined (max attempts):
                  summary: 第三次输入错误验证码 — 验证最终判定为已拒绝
                  value:
                    request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24
                    status: Declined
                    message: >-
                      The verification code is incorrect. Maximum attempts
                      reached.
                    phone:
                      status: Declined
                      phone_number_prefix: '+1'
                      phone_number: '4155552671'
                      full_number: '+14155552671'
                      country_code: US
                      country_name: United States
                      carrier:
                        name: AT&T
                        type: mobile
                      is_disposable: false
                      is_virtual: false
                      verification_method: whatsapp
                      verification_attempts: 1
                      verified_at: null
                      warnings:
                        - feature: PHONE
                          risk: VERIFICATION_CODE_ATTEMPTS_EXCEEDED
                          additional_data: null
                          log_type: error
                          short_description: Verification code attempts exceeded
                          long_description: >-
                            The system detected that the phone number has
                            exceeded the maximum number of verification code
                            attempts.
                      lifecycle:
                        - type: PHONE_VERIFICATION_MESSAGE_SENT
                          timestamp: '2026-06-12T01:23:39.580554+00:00'
                          details:
                            status: Success
                            reason: null
                            channel: whatsapp
                            actual_channel: whatsapp
                          fee: 0.0509
                        - type: INVALID_CODE_ENTERED
                          timestamp: '2026-06-12T01:24:01.118220+00:00'
                          details:
                            code_tried: '111111'
                            status: Failed
                          fee: 0
                        - type: INVALID_CODE_ENTERED
                          timestamp: '2026-06-12T01:24:21.512340+00:00'
                          details:
                            code_tried: '222222'
                            status: Failed
                          fee: 0
                        - type: INVALID_CODE_ENTERED
                          timestamp: '2026-06-12T01:24:47.311201+00:00'
                          details:
                            code_tried: '333333'
                            status: Failed
                          fee: 0
                        - type: PHONE_VERIFICATION_DECLINED
                          timestamp: '2026-06-12T01:24:47.384292+00:00'
                          details:
                            reason: VERIFICATION_CODE_ATTEMPTS_EXCEEDED
                          fee: 0
                      matches: []
                    vendor_data: user-1234
                    metadata: null
                    created_at: '2026-06-12T01:24:47.401719+00:00'
                Declined (risk policy):
                  summary: 验证码正确，但线路为 VoIP 且 voip_number_action=DECLINE
                  value:
                    request_id: 7f1c9d2e-44a1-4b6e-9a3e-5b8e6f1c2d3a
                    status: Declined
                    message: The verification code is correct.
                    phone:
                      status: Declined
                      phone_number_prefix: '+1'
                      phone_number: '5005550006'
                      full_number: '+15005550006'
                      country_code: US
                      country_name: United States
                      carrier:
                        name: CLEC LLC
                        type: voip
                      is_disposable: false
                      is_virtual: true
                      verification_method: sms
                      verification_attempts: 1
                      verified_at: '2026-06-12T01:24:47.311323Z'
                      warnings:
                        - feature: PHONE
                          risk: VOIP_NUMBER_DETECTED
                          additional_data: null
                          log_type: error
                          short_description: VoIP number detected
                          long_description: >-
                            The system detected that the phone number is a VoIP
                            number, which is not allowed.
                      lifecycle:
                        - type: PHONE_VERIFICATION_MESSAGE_SENT
                          timestamp: '2026-06-12T01:23:39.580554+00:00'
                          details:
                            status: Success
                            reason: null
                            channel: whatsapp
                            actual_channel: sms
                          fee: 0.0509
                        - type: VALID_CODE_ENTERED
                          timestamp: '2026-06-12T01:24:47.311201+00:00'
                          details:
                            code_tried: '123456'
                            status: Approved
                          fee: 0
                        - type: PHONE_VERIFICATION_DECLINED
                          timestamp: '2026-06-12T01:24:47.384292+00:00'
                          details:
                            reason: VOIP_NUMBER_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: 69cc35c6-280a-47a6-ab8c-4f32abc02ed0
                    status: Expired or Not Found
                    message: No pending phone verification found in the last 5 minutes.
                    vendor_data: null
                    metadata: null
                    created_at: '2026-06-12T01:24:47.311323+00:00'
        '400':
          description: 验证错误 — DRF 的字段错误包装格式：每个违规字段对应一个消息数组。
          content:
            application/json:
              examples:
                Invalid code format:
                  summary: '`code` 不是 4–8 位纯数字'
                  value:
                    code:
                      - Invalid code format. Enter 4 to 8 numeric digits.
                Invalid phone number:
                  summary: '`phone_number` 不是有效的 E.164 格式'
                  value:
                    phone_number:
                      - Invalid phone number provided.
                Invalid action:
                  summary: 风险操作仅接受 NO_ACTION 或 DECLINE
                  value:
                    voip_number_action:
                      - '"REVIEW" is not a valid choice.'
        '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 次额度）。此外，上游对每个电话号码每小时设置了 4
            次验证尝试的防滥用上限。响应包含
            `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和
            `Retry-After` 响应头。注意：`X-RateLimit-*`/`Retry-After` 响应头仅伴随 300
            次/分钟写入限制的 429 响应；针对每个号码上限的 429 响应不包含速率限制响应头。
          content:
            application/json:
              examples:
                Per-number cap:
                  summary: 过去一小时内同一号码的验证尝试超过 4 次
                  value:
                    detail: >-
                      Maximum verification attempts reached for this phone
                      number. Only 4 authentication attempts are allowed per
                      hour. Try again later or use a different number.
                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
        '500':
          description: 向上游核验验证码时发生意外故障，且并非已知的提供商服务中断。可安全重试；尝试次数额度仅由已完成的检查消耗。
          content:
            application/json:
              examples:
                Provider error:
                  summary: 验证码验证无法完成
                  value:
                    detail: Error checking phone verification
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '502':
          description: 电话验证服务商暂时不可用：在内置重试后仍出现 5xx 响应、超时或连接失败。可以安全重试；不会消耗尝试额度。
          content:
            application/json:
              examples:
                Provider outage:
                  summary: 服务商未响应检查请求
                  value:
                    detail: >-
                      Phone verification is temporarily unavailable. Please try
                      again shortly.
                    code: phone_provider_unavailable
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  code:
                    type: string
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/phone/check/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "phone_number": "+14155552671",
                "code": "123456",
                "voip_number_action": "DECLINE"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.phone.check_code(
                phone_number="+14155552671",
                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.phone.checkCode({
              phone_number: "+14155552671",
              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.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{\n\tPhoneNumber: \"+14155552671\",\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.PhoneCheckCodeParams;

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

            var result = client.phone().checkCode(PhoneCheckCodeParams.builder()
                    .phoneNumber("+14155552671")
                    .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->phone->checkCode([
                'phone_number' => '+14155552671',
                'code' => '123456',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.phone.check_code(
              phone_number: "+14155552671",
              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.Phone.CheckCodeAsync(new
            PhoneCheckCodeParams

            {
                PhoneNumber = "+14155552671",
                Code = "123456",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    PhoneVerificationCheckResponse:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            状态为 `Approved`/`Declined` 时：匹配验证的会话 ID，与 `POST /v3/phone/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: 结果的便于人类阅读的说明，包括输入错误验证码后的剩余尝试次数。
        phone:
          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` 一致。
            phone_number_prefix:
              type: string
              description: 带前导 `+` 的国家/地区国际呼叫代码（例如 `+1`）。
              example: '+1'
            phone_number:
              type: string
              description: 不含国家/地区呼叫代码的国内号码。
              example: '4155552671'
            full_number:
              type: string
              description: E.164 格式的完整号码。
              example: '+14155552671'
            country_code:
              type: string
              nullable: true
              description: 号码所在国家/地区的 ISO 3166-1 alpha-2 代码。
              example: US
            country_name:
              type: string
              description: 从 `country_code` 推导出的国家/地区全称。
              example: United States
            carrier:
              type: object
              description: 当前为该号码提供服务的网络，来自完成阶段运行的运营商查询。
              properties:
                name:
                  type: string
                  description: 运营商名称。当查询无法识别时为空字符串。
                type:
                  type: string
                  description: >-
                    查询报告的线路类型：`mobile`、`fixed_line`、`voip`、`isp`、`vpn`、`toll_free`、`premium_rate`、`pager`、`payphone`、`satellite`、`service`、`shared_cost`、`short_codes_commercial`、`calling_cards`、`local_rate`、`universal_access`、`voice_mail`、`other`
                    或 `unknown`。
            is_disposable:
              type: boolean
              description: 当号码属于临时/一次性号码服务时为 `true`。
            is_virtual:
              type: boolean
              description: 当线路类型为虚拟线路（`voip`、`isp` 或 `vpn`）时为 `true`。
            verification_method:
              type: string
              description: 投递确认后实际投递 OTP 的渠道（例如 `whatsapp`、`sms`）；在此之前为请求的渠道。
            verification_attempts:
              type: integer
              description: 此验证发送 OTP 的次数（1 次，重试后为 2 次）。
            verified_at:
              type: string
              format: date-time
              nullable: true
              description: 输入正确代码的时间。如果验证从未通过，则为 `null`。
            warnings:
              type: array
              description: 验证期间记录的风险警告（重复、一次性、VoIP、超出尝试次数、黑名单等）。无任何警告时为空数组。
              items:
                type: object
                properties:
                  feature:
                    type: string
                    description: 产生该警告的功能。在此处始终为 `PHONE`。
                  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`
                为以下之一：`PHONE_VERIFICATION_MESSAGE_SENT`、`PHONE_VERIFICATION_RETRY_MESSAGE_SENT`、`PHONE_VERIFICATION_BLOCKED`、`PHONE_DELIVERY_DELIVERED`、`PHONE_DELIVERY_UNDELIVERABLE`、`VALID_CODE_ENTERED`、`INVALID_CODE_ENTERED`、`PHONE_VERIFICATION_APPROVED`、`PHONE_VERIFICATION_DECLINED`、`PHONE_VERIFICATION_IN_REVIEW`、`PHONE_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, channel,
                      actual_channel}`（确认投递后填充 `actual_channel`）。投递事件：`{channel,
                      status}`。验证码输入事件：`{code_tried,
                      status}`。最终状态事件：`null`，或在已拒绝或审核中时为 `{reason}`。
                  fee:
                    type: number
                    description: 此事件计费的美元金额。仅在发送事件（投递价格）时不为零；对于验证码输入、投递确认和状态事件为 0。
            matches:
              type: array
              description: >-
                您应用中由不同用户（不同 `vendor_data`）使用相同电话号码的其他会话（KYC、KYB 或 API）。最多 5
                条记录，存在合成列表条目黑名单匹配时优先排列（从会话派生的匹配保留查询顺序）。无匹配项时为空数组。
              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`）。
                  phone_number:
                    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。
            phone_social:
              $ref: '#/components/schemas/PhoneSocialFootprint'
            phone_intelligence:
              allOf:
                - $ref: '#/components/schemas/PhoneIntelligence'
              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: 此检查响应的时间戳。
    PhoneSocialFootprint:
      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'
    PhoneIntelligence:
      type: object
      description: 归一化的电话情报区块。仅在本次查询运行了情报附加组件时存在；存在时还会以相同值的 `enrichment` 别名提供。
      properties:
        score:
          type: number
          nullable: true
          description: 归一化的 0-100 风险评分。分值越高风险越大。
        phone_type_risk:
          type: string
          nullable: true
          description: 由评分推导出的 `Low`、`Medium` 或 `High`。
        phone_trust_index:
          type: number
          nullable: true
          description: 分数的反向值，适用于偏好数值越高越好的仪表板。
        network_stability_index:
          type: number
          nullable: true
          description: 线路网络的稳定性。
        is_disposable:
          type: boolean
          nullable: true
          description: 当号码疑似一次性号码或虚拟号码时为 `true`。
        is_ported:
          type: boolean
          nullable: true
          description: 当号码已更换运营商时为 `true`。
        is_recently_ported:
          type: boolean
          nullable: true
          description: 当转网发生在近期时为 `true`。
        carrier_type:
          type: string
          nullable: true
          description: 查询报告的线路分类（例如 `mobile`）。
        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.