> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 电话号码验证 API

> Cleariflow 快速 REST JSON API：结构性电话验证、E.164 规范化及可选的运营商、位置、时区和拨号详情。

使用非常简单：提交 API 密钥和电话号码即可。API 返回号码是否**结构有效**，有效时还会返回规范化的 E.164 格式以及线路类型、地理编码、运营商、时区和拨号提示等可选元数据。

<Note>
  `valid: true` 表示号码符合区域格式规则（长度、前缀、语法）。这**并不**确认线路处于活跃状态、已分配给用户或可以接通。实时线路状态需要 carrier lookup，不在本 API 范围内。
</Note>

## 入门

### 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`  | 号码对其检测到的区域在结构上有效（）。                                                                                                                                                                                                                  |
| `false` | 号码无法解析或不符合地区格式规则。`valid` 为 false 时，`format`、`country`、`location`、`type`、`carrier`、`carrier_display`、`timezones`、`geographical` 和 `internationally_dialable` 始终为空或 false；若能解析输入，仍会返回 `possible` 和 `invalid_reason`。`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`）：

<ResponseExample>
  ```json theme={"system"}
  {
    "phone": "14155552671",
    "valid": true,
    "possible": 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": "",
    "carrier_display": "",
    "timezones": ["America/Los_Angeles"],
    "geographical": true,
    "internationally_dialable": true
  }
  ```
</ResponseExample>

**无效响应**（`phone=123`，`country=US`）：

```json theme={"system"}
{
  "phone": "123",
  "valid": false,
  "possible": false,
  "invalid_reason": "too_short",
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": "",
  "carrier_display": "",
  "timezones": null,
  "geographical": false,
  "internationally_dialable": false
}
```

### 请求参数

<ParamField query="api_key" type="String" required>
  您的唯一 API 密钥。请注意，每位用户对\_每个 Cleariflow API\_ 都有独立的 API 密钥，因此您的 Phone Validation API 密钥无法用于 IP 地理定位 API 等。
</ParamField>

<ParamField query="phone" type="String" required>
  待验证的电话号码。
</ParamField>

<ParamField query="country" type="String">
  针对不带前导 `+` 的国内格式号码的可选 ISO 3166-1 alpha-2 提示。例如，`country=US` 有助于解析 `4155552671`。带国际前缀的号码按其国家代码解析；响应中检测到的 `country.code` 可能与此提示不同（例如部分 `+44` 移动号段为 `GG`）。
</ParamField>

### 响应参数

API 响应以通用轻量的 [JSON 格式](https://www.json.org/json-en.html) 返回。

<ResponseField name="phone" type="String">
  当 `valid` 为 true 时，规范化的 E.164 数字（不含 `+`）。当 `valid` 为 false 时，仅包含您输入中的数字。
</ResponseField>

<ResponseField name="valid" type="Boolean">
  当号码在结构上有效时为 `true`。这**不是**线路状态或用户验证。
</ResponseField>

<ResponseField name="possible" type="Boolean">
  宽松的长度检查（）。即使 `valid` 为 false，若数字和长度可能属于真实号码，则为 `true`。
</ResponseField>

<ResponseField name="invalid_reason" type="String">
  在 `valid` 为 false 时返回。取值为：`not_a_number`、`possible`、`possible_local_only`、`invalid_country_code`、`too_short`、`invalid_length`、`too_long`、`unknown`。`valid` 为 true 时省略。
</ResponseField>

<ResponseField name="format" type="Object">
  `international` 和 `local` 格式。当 `valid` 为 false 时为空字符串。
</ResponseField>

<ResponseField name="format.international" type="String">
  带前导 `+` 的 E.164 格式。当 `valid` 为 false 时为空。
</ResponseField>

<ResponseField name="format.local" type="String">
  检测区域的国内格式。当 `valid` 为 false 时为空。
</ResponseField>

<ResponseField name="country" type="Object">
  检测到的国家/地区。当 `valid` 为 false 时字段为空。
</ResponseField>

<ResponseField name="country.code" type="String">
  检测区域的两位 [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) 代码。
</ResponseField>

<ResponseField name="country.name" type="String">
  `country.code` 的英文显示名称。
</ResponseField>

<ResponseField name="country.prefix" type="String">
  国际[电话区号](https://en.wikipedia.org/wiki/List_of_country_calling_codes)（例如 `+1`）。
</ResponseField>

<ResponseField name="location" type="String">
  地理编码提示（地区、州/省或城市）。US/CA 以外通常为空。当 `valid` 为 false 时为空。
</ResponseField>

<ResponseField name="type" type="String">
  当 `valid` 为 true 时的线路类型：`Landline`、`Mobile`、`Landline_or_Mobile`、`Toll_Free`、`Premium`、`Paging`、`Special` 或 `Unknown`。当 `valid` 为 false 时始终为 `Unknown`。
</ResponseField>

<ResponseField name="carrier" type="String">
  可用时运营商名称（最常见为 US/CA）。否则为空字符串，包括当 `valid` 为 false 时。
</ResponseField>

<ResponseField name="carrier_display" type="String">
  面向终端用户的安全运营商名称（号码有效且地区不支持携号转网时）。`valid` 为 false 或无法安全显示时为空。
</ResponseField>

<ResponseField name="timezones" type="Array">
  号码对应的 时区标识（如 `America/New_York`）。`valid` 为 true 但无映射时为空数组；`valid` 为 false 时为 `null`。
</ResponseField>

<ResponseField name="geographical" type="Boolean">
  号码是否与地理区域关联。`valid` 为 false 时始终为 `false`。
</ResponseField>

<ResponseField name="internationally_dialable" type="Boolean">
  是否可从归属地区以外拨打。`valid` 为 false 时始终为 `false`。
</ResponseField>

## 批量上传（CSV）

批量上传 CSV 文件时的最佳实践：

* 确保第一列包含待分析的电话号码。
* 删除文件中的空行。
* 每行仅包含一个电话号码。
* 允许的最大文件大小为 50,000 行。

## 响应和错误代码

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

| Code | Type                  | Details                            |
| ---- | --------------------- | ---------------------------------- |
| 200  | OK                    | 一切按预期运行。                           |
| 400  | Bad request           | 错误请求。                              |
| 401  | Unauthorized          | 请求不可接受。通常由于 API 密钥缺失或错误。           |
| 422  | Quota reached         | 由于 API 额度不足，请求已中止。（免费套餐）           |
| 429  | Too many requests     | 由于达到每秒允许请求数，请求已中止。免费套餐限制为每秒 1 次请求。 |
| 500  | Internal server error | 由于服务器端错误，无法完成请求。                   |
| 503  | Service unavailable   | 服务器不可用。                            |

## 其他说明

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