> ## 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/phone/risk/`，在 OTP 流程之前、代替 OTP 流程或在 OTP 流程之外获取电话情报。

它不会向用户发送验证码。它会创建一个 API 会话，对号码进行信息补充，应用你的电话风险规则，并在一次同步响应中返回与电话验证相同的标准化电话信息块。

保存请求后，Didit 还可以将已评分的电话号码作为汇总证据用于**网络**。网络图谱可能会在共享电话信号上显示高风险电话情报、携号转网和线路类型信息，但不会向其他机构披露原始电话号码。

## 解读响应

* `status` 是此 API 会话的最终决策。通常为 `Approved`；风险评估可能得出 `In Review` 或 `Declined`。
* `phone.full_number` 是标准化的 E.164 号码。`phone.phone_number_prefix` 和 `phone.phone_number` 将其拆分为国际区号和国内号码。
* `phone.is_disposable` 和 `phone.is_virtual` 是供应用逻辑使用的稳定是/否信号。运营商查询会额外返回 `carrier.name` 和 `carrier.type`（`mobile`、`voip` 等）。
* `phone.phone_intelligence.score` 采用 0-100 的风险刻度，数值越高表示风险越高。`phone_type_risk`（`Low`、`Medium`、`High`）和 `phone_trust_index`（分数的反向值）是派生视图。
* `phone.phone_intelligence` 和 `phone.enrichment` 是指向同一标准化对象的兼容别名。新集成可以读取 `phone.enrichment`。
* `phone.matches` 列出你的应用中，同一号码曾被其他用户用于其他会话的记录。可用于重复账户检测。
* `request_id` 是 API 会话 ID。如果需要将结果与后续 Webhook 或控制台活动关联，请将其与 `vendor_data` 一起存储。

> [!WARNING]
>
> `phone.phone_intelligence` 和 `phone.enrichment` 是尽力返回的字段。即使查询已完成，如果该号码、国家/地区或套餐没有可用的情报数据，两者都可能缺失。请先基于稳定的标准化字段构建规则，并将缺失的情报视为“未知”，而不是“安全”。

## 社交足迹附加功能

将 `enable_social` 设为 `true`，即可在响应的 `phone` 下添加 `phone_social` 块：该电话号码注册过的在线平台，按类别分组，并附带汇总计数以及数据合作伙伴返回的任何资料详情。

* `phone.phone_social.profiles_registered` 和 `phone.phone_social.profiles_checked` 是核心数字：已确认注册该电话号码的平台数，以及参与评估的平台总数。
* `phone.phone_social.registered_platforms` 和 `phone.phone_social.not_registered_platforms` 列出每个平台及其 `category` 和 `scope`（`global` 表示全球平台，`local` 表示特定地区平台）。
* `phone.phone_social.categories` 提供每个类别的已注册数量和比例。当平台提供资料时，`phone.phone_social.profiles` 会附带每个平台的资料详情（名称、头像 URL、简介文本、隐私状态、是否为企业账户）。
* 汇总指数（`digital_footprint_diversity`、`digital_sophistication_index`、`engagement_depth_index`、`subscription_affordability_index`）是 0-10 的综合评分。如果检查未返回某项数据，任何计数都可能为 `null`。

`profiles_registered: 0` 是有效结果，而不是失败：平台已被检查，并且在所有平台上都未找到该电话号码。这通常是合成身份信号。此端点本身不会据此采取行动。如需将其转换为审核或拒绝判定，请在工作流中使用 `phone_no_social_presence_action`。

未设置 `enable_social` 时，不会返回该块；社交检查无法完成时也不会返回，此时该次检查不计费。

## 沙盒行为

沙盒密钥会验证请求，并返回确定性的已通过数据。它们不会发送 OTP、消耗额度、创建会话或向网络贡献数据。设置 `enable_social` 后，沙盒还会返回确定性的 `phone_social` 块。

## 计费

电话风险 API 调用的标准价格为 \$0.04，低于完整电话验证的价格，因为不发送 OTP。正式环境中的请求在查询开始后即产生费用，即使部分尽力返回的字段不可用也是如此。

社交足迹附加功能单独计费：每个请求在电话风险 API 价格之外，还会在检查完成时计一个 `phone_social` 单位。查询前的额度检查同时覆盖两项费用。


## OpenAPI

````yaml zh/openapi-25.json POST /v3/phone/risk/
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/risk/:
    post:
      tags:
        - Standalone APIs
      summary: 对电话号码进行风险评分
      description: >-
        解析电话号码，并在不发送 OTP 的情况下返回运营商、线路类型、携号转网、一次性号码、跨会话匹配以及归一化风险情报信号。该 endpoint
        会创建一个 API 会话，并将其 ID 作为 `request_id` 返回。


        **决策。** 顶层的 `status` 与 `phone.status` 保持一致。通常为 `Approved`；风险评估可能会产生 `In
        Review` 或 `Declined`。


        **兼容性别名。** 生产环境响应将归一化情报对象同时公开为 `phone.phone_intelligence` 和
        `phone.enrichment`。两者值完全一致。新的集成可读取
        `phone.enrichment`。若未返回可用的情报数据，则两个键均不存在。


        **计费。** 生产环境调用采用 Phone Risk API 定价。一旦开始查询，即使某些尽力而为的字段不可用，该请求也将被计费。


        **沙盒。** 沙盒密钥会验证请求并返回确定性的已通过数据，而无需发送 OTP、消耗额度、创建会话或向 Networks 提供数据。


        **身份验证。** 在 `x-api-key` 中发送您应用的 API 密钥。缺少或无效的凭据将返回 `403`，该 API 从不返回
        `401`。


        **速率限制。** 所有 POST/PATCH/DELETE endpoints 共享每个 API 密钥每分钟 300
        次请求的写入配额（交易创建和事件摄入具有单独的 600 次配额）。


        **社交足迹。** 将 `enable_social` 设置为 `true` 可添加 `phone_social`
        区块：该号码注册过的在线平台、各分类计数以及任何可用的个人资料详情。`profiles_registered: 0`
        表示已检查相关平台且未在其中任何一个发现该号码，这是一个有效且计费的回答。如果未请求该附加功能或检查无法完成，则不包含该区块，在此情况下亦不计费。计费时会在该
        endpoint 自身价格的基础上，按每次请求增加一个 `phone_social` 计费单位。
      operationId: post_v3phone_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneRiskRequest'
            examples:
              Minimal:
                summary: 使用默认值对号码评分
                value:
                  phone_number: '+14155552671'
              Full context:
                summary: 附带信号、国家/地区提示和关联 ID 的评分
                value:
                  phone_number: '+14155552671'
                  country_code: US
                  signals:
                    ip: 192.0.2.1
                    device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2
                    device_platform: ios
                    device_model: iPhone17,2
                    os_version: 18.0.1
                    app_version: 1.2.34
                    user_agent: >-
                      Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X)
                      AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0
                      Mobile/15E148 Safari/604.1
                  vendor_data: lead-123
                  metadata:
                    source: signup_prescreen
      responses:
        '200':
          description: 风险评估已完成。检查 `status` 获取决策；对于已完成的查询，HTTP 状态码始终为 `200`。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneRiskResponse'
              examples:
                Clean mobile number:
                  summary: 经过清理且具备情报覆盖的移动电话号码
                  value:
                    request_id: 4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62
                    status: Approved
                    phone:
                      status: Approved
                      phone_number_prefix: '+1'
                      phone_number: '4155552671'
                      full_number: '+14155552671'
                      country_code: US
                      country_name: United States
                      carrier:
                        name: Example Mobile
                        type: mobile
                      is_disposable: false
                      is_virtual: false
                      verification_method: null
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      phone_intelligence:
                        score: 3
                        phone_type_risk: Low
                        phone_trust_index: 97
                        network_stability_index: 95
                        is_disposable: false
                        is_ported: false
                        is_recently_ported: false
                        carrier_type: mobile
                        reason_codes: []
                      enrichment:
                        score: 3
                        phone_type_risk: Low
                        phone_trust_index: 97
                        network_stability_index: 95
                        is_disposable: false
                        is_ported: false
                        is_recently_ported: false
                        carrier_type: mobile
                        reason_codes: []
                    vendor_data: lead-123
                    metadata:
                      source: signup_prescreen
                    created_at: '2026-09-01T10:30:00.123456+00:00'
                Number in review:
                  summary: 标记待审核的一次性或虚拟号码
                  value:
                    request_id: 8c22e1f0-4b3d-4a3a-9d1e-2f6b7c8d9e0f
                    status: In Review
                    phone:
                      status: In Review
                      phone_number_prefix: '+44'
                      phone_number: '7700900123'
                      full_number: '+447700900123'
                      country_code: GB
                      country_name: United Kingdom
                      carrier:
                        name: Example VoIP
                        type: voip
                      is_disposable: true
                      is_virtual: true
                      verification_method: null
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      phone_intelligence:
                        score: 72
                        phone_type_risk: High
                        phone_trust_index: 28
                        network_stability_index: 40
                        is_disposable: true
                        is_ported: true
                        is_recently_ported: true
                        carrier_type: voip
                        reason_codes:
                          - code: IR-5AC67A32
                            direction: risk
                            message: Phone type identified as non-mobile
                            impact_level: medium
                      enrichment:
                        score: 72
                        phone_type_risk: High
                        phone_trust_index: 28
                        network_stability_index: 40
                        is_disposable: true
                        is_ported: true
                        is_recently_ported: true
                        carrier_type: voip
                        reason_codes:
                          - code: IR-5AC67A32
                            direction: risk
                            message: Phone type identified as non-mobile
                            impact_level: medium
                    vendor_data: lead-124
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
        '400':
          $ref: '#/components/responses/PhoneRiskValidationError'
        '403':
          $ref: '#/components/responses/RiskPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/phone/risk/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "phone_number": "+14155552671",
                "country_code": "US",
                "vendor_data": "lead-123",
                "metadata": {"source": "signup_prescreen"}
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.phone.assess_risk(
                phone_number="+14155552671",
            )
            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.assessRisk({
              phone_number: "+14155552671",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.AssessRisk(ctx, didit.PhoneRiskRequest{\n\tPhoneNumber: \"+14155552671\",\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.PhoneRiskRequest;

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

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

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

            result = didit.phone.assess_risk(phone_number: "+14155552671")
            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.AssessRiskAsync(new PhoneRiskRequest
            {
                PhoneNumber = "+14155552671",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    PhoneRiskRequest:
      type: object
      required:
        - phone_number
      properties:
        phone_number:
          type: string
          maxLength: 20
          description: 待评分的电话号码。它将被验证并规范化为 E.164 格式。
          example: '+14155552671'
        country_code:
          type: string
          maxLength: 3
          description: 用于情报覆盖范围的可选 ISO 3166-1 alpha-2 或 alpha-3 国家/地区提示。
          example: US
        signals:
          $ref: '#/components/schemas/RiskSignals'
        vendor_data:
          type: string
          description: 您为此请求提供的稳定引用。存储在 API 会话中并在响应中返回。
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: 您的非敏感 JSON 元数据。存储在 API 会话中并在响应中原样返回。
        enable_social:
          type: boolean
          default: false
          description: >-
            为 true 时，还会查找该号码的社交足迹，即其注册所在的消息、社交、电子商务和职业平台。除此 endpoint
            本身的价格外，每次请求按一个 `phone_social` 计费。
          example: true
    PhoneRiskResponse:
      type: object
      required:
        - request_id
        - status
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            为此请求创建的 API 会话 ID。如果您需要将结果与后续的 Webhook 或控制台活动关联，请将其与 `vendor_data`
            一同存储。
        status:
          type: string
          enum:
            - Approved
            - In Review
            - Declined
          description: 此 API 会话的最终决策。通常为 `Approved`；风险评估可能会产生 `In Review` 或 `Declined`。
        vendor_data:
          type: string
          nullable: true
          description: 您发送的 `vendor_data` 回显，若未发送则为 `null`。
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: 您发送的 `metadata` 回显，若未发送则为 `null`。
        created_at:
          type: string
          format: date-time
          description: 此响应的时间戳。
        phone:
          type: object
          description: 归一化的电话报告，与电话验证响应所使用的区块相同。
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
                - Declined
              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
              nullable: true
              description: 当前为该号码提供服务的网络。当查询无法解析运营商时为 `null`。
              properties:
                name:
                  type: string
                  description: 运营商名称。当查询无法识别时为空字符串。
                type:
                  type: string
                  description: >-
                    查询报告的线路类型：`mobile`、`fixed_line`、`voip`、`isp`、`vpn`、`toll_free`、`premium_rate`
                    或类似类型。
            is_disposable:
              type: boolean
              description: 当号码属于临时或一次性号码服务时为 `true`。
            is_virtual:
              type: boolean
              description: 当线路类型为虚拟线路（`voip`、`isp` 或 `vpn`）时为 `true`。
            verification_method:
              type: string
              nullable: true
              description: 底层验证的 OTP 渠道。对于绝不发送验证码的风险查询为 `null`。
            verification_attempts:
              type: integer
              description: 此号码的一次性验证码发送次数。风险查询为 `0`。
            verified_at:
              type: string
              format: date-time
              nullable: true
              description: 该号码最后一次通过一次性验证码验证的时间。对于风险查询为 `null`。
            warnings:
              type: array
              description: 为此请求记录的风险警告。无任何警告时为空数组。
              items:
                $ref: '#/components/schemas/RiskWarning'
            lifecycle:
              type: array
              description: 请求的时间顺序审计记录。对于没有发送事件的风险查询，此项为空数组。
              items:
                $ref: '#/components/schemas/RiskLifecycleEvent'
            matches:
              type: array
              description: 您应用中由不同用户（不同 `vendor_data`）使用相同电话号码的其他会话。最多 5 条记录。无匹配项时为空数组。
              items:
                $ref: '#/components/schemas/PhoneMatchItem'
            phone_intelligence:
              $ref: '#/components/schemas/PhoneIntelligence'
            enrichment:
              $ref: '#/components/schemas/PhoneIntelligence'
            phone_social:
              $ref: '#/components/schemas/PhoneSocialFootprint'
    RiskSignals:
      type: object
      description: 您的应用所观测到的可选设备和网络上下文。所有字段均为可选。传入这些字段有助于为 Networks 中的跨会话匹配检测提供数据。
      properties:
        ip:
          type: string
          format: ip
          description: 观察到的终端用户的 IPv4 或 IPv6 地址。
          example: 192.0.2.1
        device_id:
          type: string
          maxLength: 255
          description: 应用收集的稳定设备标识符（Android 为 `ANDROID_ID`，iOS 为 `identifierForVendor`）。
        device_platform:
          type: string
          enum:
            - android
            - ios
            - ipados
            - tvos
            - web
          description: 终端用户设备的平台。
        device_model:
          type: string
          maxLength: 255
          description: 您的应用报告的设备型号。
        os_version:
          type: string
          maxLength: 64
          description: 操作系统版本。
        app_version:
          type: string
          maxLength: 64
          description: 您的应用版本。
        user_agent:
          type: string
          maxLength: 512
          description: 浏览器或应用的 user agent。
    RiskWarning:
      type: object
      required:
        - feature
        - risk
        - log_type
        - short_description
        - long_description
      properties:
        feature:
          type: string
          description: 产生该警告的功能。
        risk:
          type: string
          description: 机器可读的风险代码。后续可能会随着时间推移添加新值。
        additional_data:
          type: object
          nullable: true
          additionalProperties: true
          description: 特定风险的上下文，或 `null`。
        log_type:
          type: string
          enum:
            - error
            - warning
            - information
          description: 决策规则所使用的严重程度。
        short_description:
          type: string
          description: 易于阅读的单行摘要。
        long_description:
          type: string
          description: 便于人类阅读的说明。
    RiskLifecycleEvent:
      type: object
      required:
        - type
        - timestamp
        - details
        - fee
      properties:
        type:
          type: string
          description: 机器可读的事件类型。新值可能会随着时间推移而添加。
        timestamp:
          type: string
          format: date-time
          description: 事件发生的时间。
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: 特定事件的 payload，或为 `null`。
        fee:
          type: number
          description: 此事件计费的美元金额。
    PhoneMatchItem:
      type: object
      description: 您应用中使用了相同电话号码但具有不同 `vendor_data` 的另一个会话。
      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；对于常规验证会话为 `null`。
        source:
          type: string
          description: 发现匹配的位置。通常为 `session`；通过组织名单条目命中的黑名单使用 `list_entry`。
    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
            代码、一个方向、一条消息和一个影响级别。新代码可能会随着时间推移而出现，因此请勿拒绝未知代码。
    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'
    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: 该资料是否为企业账户（若平台提供该信息）。
  responses:
    PhoneRiskValidationError:
      description: 请求验证失败。
      content:
        application/json:
          examples:
            Missing phone number:
              summary: 缺少电话号码
              value:
                phone_number:
                  - This field is required.
            Invalid phone number:
              summary: 无效的电话号码
              value:
                phone_number:
                  - Invalid phone number provided.
            Invalid signal IP:
              summary: 无效的信号 IP
              value:
                signals:
                  ip:
                    - Enter a valid IPv4 or IPv6 address.
    RiskPermissionDenied:
      description: API 密钥缺失或无效，或者组织无法支付实时查询费用。此 API 从不返回 `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.
            Not enough credits:
              summary: 组织余额不足以支付查询价格
              value:
                error: You don't have enough credits to perform this request.
    RateLimitedWrite:
      description: 已超出每个 API 密钥每分钟 300 次请求的共享写入限制。在重试之前请遵循 `Retry-After`。
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  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.