Skip to main content
GET
电话号码验证 API
使用非常简单:提交 API 密钥和电话号码即可。API 返回号码是否结构有效,有效时还会返回规范化的 E.164 格式以及线路类型、地理编码、运营商、时区和拨号提示等可选元数据。
valid: true 表示号码符合区域格式规则(长度、前缀、语法)。这并不确认线路处于活跃状态、已分配给用户或可以接通。实时线路状态需要 carrier lookup,不在本 API 范围内。

入门

REST

电话号码验证 API 与所有 Cleariflow API 一样基于 REST 构建,采用可预测的资源导向 URL,并使用 HTTP 状态码指示错误。

HTTPS

电话号码验证 API 要求所有通信均使用 TLS 1.2 或更高版本进行保护。

API 版本

所有 Cleariflow API 均带版本号。电话号码验证 API 当前为第 1 版。

您的 API 密钥

API 密钥是您访问 Cleariflow 电话号码验证 API 的唯一身份验证密钥。请注意,每个 Cleariflow API 都有独立的 API 密钥,因此访问电话验证和电子邮件验证等功能需要使用不同的密钥。要对请求进行身份验证,请将 API 密钥附加到基础 URL。

基础 URL

valid 的含义

虚构的美国 555 号码及其他结构上有效但未分配的号段仍可能返回 valid: truecarrierlocation 主要从 US/CA 元数据填充,在其他地区通常为空。

验证端点

API 需要您的唯一 API 密钥和待验证的电话号码:
有效响应phone=14155552671country=US):
无效响应phone=123country=US):

请求参数

String
必填
您的唯一 API 密钥。请注意,每位用户对_每个 Cleariflow API_ 都有独立的 API 密钥,因此您的 Phone Validation API 密钥无法用于 IP 地理定位 API 等。
String
必填
待验证的电话号码。
String
针对不带前导 + 的国内格式号码的可选 ISO 3166-1 alpha-2 提示。例如,country=US 有助于解析 4155552671。带国际前缀的号码按其国家代码解析;响应中检测到的 country.code 可能与此提示不同(例如部分 +44 移动号段为 GG)。

响应参数

API 响应以通用轻量的 JSON 格式 返回。
String
valid 为 true 时,规范化的 E.164 数字(不含 +)。当 valid 为 false 时,仅包含您输入中的数字。
Boolean
当号码在结构上有效时为 true。这不是线路状态或用户验证。
Boolean
宽松的长度检查()。即使 valid 为 false,若数字和长度可能属于真实号码,则为 true
String
valid 为 false 时返回。取值为:not_a_numberpossiblepossible_local_onlyinvalid_country_codetoo_shortinvalid_lengthtoo_longunknownvalid 为 true 时省略。
Object
internationallocal 格式。当 valid 为 false 时为空字符串。
String
带前导 + 的 E.164 格式。当 valid 为 false 时为空。
String
检测区域的国内格式。当 valid 为 false 时为空。
Object
检测到的国家/地区。当 valid 为 false 时字段为空。
String
检测区域的两位 ISO 3166-1 alpha-2 代码。
String
country.code 的英文显示名称。
String
国际电话区号(例如 +1)。
String
地理编码提示(地区、州/省或城市)。US/CA 以外通常为空。当 valid 为 false 时为空。
String
valid 为 true 时的线路类型:LandlineMobileLandline_or_MobileToll_FreePremiumPagingSpecialUnknown。当 valid 为 false 时始终为 Unknown
String
可用时运营商名称(最常见为 US/CA)。否则为空字符串,包括当 valid 为 false 时。
String
面向终端用户的安全运营商名称(号码有效且地区不支持携号转网时)。valid 为 false 或无法安全显示时为空。
Array
号码对应的 时区标识(如 America/New_York)。valid 为 true 但无映射时为空数组;valid 为 false 时为 null
Boolean
号码是否与地理区域关联。valid 为 false 时始终为 false
Boolean
是否可从归属地区以外拨打。valid 为 false 时始终为 false

批量上传(CSV)

批量上传 CSV 文件时的最佳实践:
  • 确保第一列包含待分析的电话号码。
  • 删除文件中的空行。
  • 每行仅包含一个电话号码。
  • 允许的最大文件大小为 50,000 行。

响应和错误代码

当请求因某种原因失败时,也会以 JSON 格式返回错误。错误包含错误代码和描述,详见下表。

其他说明

关于按量计费:您提交的每个电话号码均计为 1 个已用额度。额度按请求计数,而非按成功响应计数。因此,即使提交无效号码「kasj8929hs」的请求,仍会计为 1 个额度。