> ## 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

> 構造的な電話番号検証、E.164 正規化、オプションのキャリア・位置・タイムゾーン・ダイヤル可否情報を提供する Cleariflow の高速 REST JSON API。

使い方は簡単です。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 のキーは 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">
  検出された地域の 2 文字 [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">
  エンドユーザー向けの安全なキャリア名（有効な番号で MNP 非対応地域の場合）。`valid` が false、または安全に表示できない場合は空。
</ResponseField>

<ResponseField name="timezones" type="Array">
  番号に対応する タイムゾーン ID（例: `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 ファイルを一括アップロードする際のベストプラクティス：

* 最初の列に分析する電話番号が含まれていることを確認してください。
* ファイルから空行を削除してください。
* 1 行に 1 つの電話番号のみを含めてください。
* 許可される最大ファイルサイズは 50,000 行です。

## レスポンスおよびエラーコード

何らかの理由でリクエストが失敗した場合、エラーも JSON 形式で返されます。エラーにはコードと説明が含まれ、以下に詳細を示します。

| Code | Type                  | Details                                                         |
| ---- | --------------------- | --------------------------------------------------------------- |
| 200  | OK                    | すべて期待どおりに動作しました。                                                |
| 400  | Bad request           | 不正なリクエスト。                                                       |
| 401  | Unauthorized          | リクエストが受け付けられませんでした。通常は API キーが欠落しているか不正です。                      |
| 422  | Quota reached         | API クレジット不足のためリクエストが中断されました。（無料プラン）                             |
| 429  | Too many requests     | 秒あたりの許可リクエスト数に達したためリクエストが中断されました。無料プランでは 1 秒あたり 1 リクエストに制限されます。 |
| 500  | Internal server error | サーバー側のエラーのためリクエストを完了できませんでした。                                   |
| 503  | Service unavailable   | サーバーが利用できませんでした。                                                |

## その他の注意事項

従量課金に関する注意：送信する各電話番号は 1 クレジットとしてカウントされます。クレジットは成功したレスポンスごとではなく、リクエストごとにカウントされます。したがって、（無効な）電話番号「kasj8929hs」のリクエストを送信しても、1 クレジットとしてカウントされます。