跳转到主要内容
GET
/
v1
电话号码验证 API
curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1
{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}
使用非常简单：提交 API 密钥和电话号码即可。API 会返回该号码是否在结构上有效（依据 Google libphonenumber），若有效则返回规范化的 E.164 格式，以及线路类型、地理编码提示和可用时的运营商数据等可选元数据。
valid: true 表示号码符合区域格式规则（长度、前缀、语法）。这并不确认线路处于活跃状态、已分配给用户或可以接通。实时线路状态需要 HLR/SMS 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

https://phonevalidation.cleariflow.com/v1/

​
valid 的含义

valid含义
true号码对其检测到的区域在结构上有效（libphonenumber IsValidNumber）。
false号码无法解析或不符合区域格式规则。format、country、location、type 和 carrier 始终为空；phone 仅包含您输入中的数字。
虚构的美国 555 号码及其他结构上有效但未分配的号段仍可能返回 valid: true。carrier 和 location 主要从 US/CA 元数据填充，在其他地区通常为空。

​
验证端点

API 需要您的唯一 API 密钥和待验证的电话号码： 
https://phonevalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14155552671
& country = US
有效响应（phone=14155552671，country=US）： 
{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}
无效响应（phone=123，country=US）： 
{
  "phone": "123",
  "valid": false,
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": ""
}

​
请求参数

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

​
响应参数

API 响应以通用轻量的 JSON 格式 返回。
​
phone
String
当 valid 为 true 时，规范化的 E.164 数字（不含 +）。当 valid 为 false 时，仅包含您输入中的数字。
​
valid
Boolean
当号码按 libphonenumber 在结构上有效时为 true。这不是线路状态或用户验证。
​
format
Object
international 和 local 格式。当 valid 为 false 时为空字符串。
​
format.international
String
带前导 + 的 E.164 格式。当 valid 为 false 时为空。
​
format.local
String
检测区域的国内格式。当 valid 为 false 时为空。
​
country
Object
检测到的国家/地区。当 valid 为 false 时字段为空。
​
country.code
String
检测区域的两位 ISO 3166-1 alpha-2 代码。
​
country.name
String
country.code 的英文显示名称。
​
country.prefix
String
国际电话区号（例如 +1）。
​
location
String
来自 libphonenumber 元数据的地理编码提示（地区、州/省或城市）。US/CA 以外通常为空。当 valid 为 false 时为空。
​
type
String
当 valid 为 true 时的线路类型：Landline、Mobile、Landline_or_Mobile、Toll_Free、Premium、Paging、Special 或 Unknown。当 valid 为 false 时始终为 Unknown。
​
carrier
String
可用时来自 libphonenumber 元数据的运营商名称（最常见为 US/CA）。否则为空字符串，包括当 valid 为 false 时。

​
批量上传（CSV）

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

​
响应和错误代码

当请求因某种原因失败时，也会以 JSON 格式返回错误。错误包含错误代码和描述，详见下表。
CodeTypeDetails
200OK一切按预期运行。
400Bad request错误请求。
401Unauthorized请求不可接受。通常由于 API 密钥缺失或错误。
422Quota reached由于 API 额度不足，请求已中止。（免费套餐）
429Too many requests由于达到每秒允许请求数，请求已中止。免费套餐限制为每秒 1 次请求。
500Internal server error由于服务器端错误，无法完成请求。
503Service unavailable服务器不可用。

​
其他说明

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