跳转到主要内容
POST
curl
使用 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 一起存储。
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 单位。查询前的额度检查同时覆盖两项费用。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

application/json
phone_number
string
必填

待评分的电话号码。它将被验证并规范化为 E.164 格式。

Maximum string length: 20
示例:

"+14155552671"

country_code
string

用于情报覆盖范围的可选 ISO 3166-1 alpha-2 或 alpha-3 国家/地区提示。

Maximum string length: 3
示例:

"US"

signals
object

您的应用所观测到的可选设备和网络上下文。所有字段均为可选。传入这些字段有助于为 Networks 中的跨会话匹配检测提供数据。

vendor_data
string

您为此请求提供的稳定引用。存储在 API 会话中并在响应中返回。

metadata
object | null

您的非敏感 JSON 元数据。存储在 API 会话中并在响应中原样返回。

enable_social
boolean
默认值:false

为 true 时,还会查找该号码的社交足迹,即其注册所在的消息、社交、电子商务和职业平台。除此 endpoint 本身的价格外,每次请求按一个 phone_social 计费。

示例:

true

响应

风险评估已完成。检查 status 获取决策;对于已完成的查询,HTTP 状态码始终为 200。

request_id
string<uuid>
必填

为此请求创建的 API 会话 ID。如果您需要将结果与后续的 Webhook 或控制台活动关联,请将其与 vendor_data 一同存储。

status
enum<string>
必填

此 API 会话的最终决策。通常为 Approved;风险评估可能会产生 In Review 或 Declined。

可用选项:
Approved,
In Review,
Declined
created_at
string<date-time>
必填

此响应的时间戳。

vendor_data
string | null

您发送的 vendor_data 回显,若未发送则为 null。

metadata
object | null

您发送的 metadata 回显,若未发送则为 null。

phone
object

归一化的电话报告,与电话验证响应所使用的区块相同。

最后修改于 2026年11月7日