验证
电话号码验证 API
Cleariflow 快速 REST JSON API:结构性电话验证、E.164 规范化及可选的运营商、位置、时区和拨号详情。
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: true。carrier 和 location 主要从 US/CA 元数据填充,在其他地区通常为空。
验证端点
API 需要您的唯一 API 密钥和待验证的电话号码:phone=14155552671,country=US):
phone=123,country=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_number、possible、possible_local_only、invalid_country_code、too_short、invalid_length、too_long、unknown。valid 为 true 时省略。Object
international 和 local 格式。当 valid 为 false 时为空字符串。String
带前导
+ 的 E.164 格式。当 valid 为 false 时为空。String
检测区域的国内格式。当
valid 为 false 时为空。Object
检测到的国家/地区。当
valid 为 false 时字段为空。String
检测区域的两位 ISO 3166-1 alpha-2 代码。
String
country.code 的英文显示名称。String
地理编码提示(地区、州/省或城市)。US/CA 以外通常为空。当
valid 为 false 时为空。String
当
valid 为 true 时的线路类型:Landline、Mobile、Landline_or_Mobile、Toll_Free、Premium、Paging、Special 或 Unknown。当 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 个额度。电话号码验证 API