メインコンテンツへスキップ
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 のキーは 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
検出された地域の 2 文字 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 ファイルを一括アップロードする際のベストプラクティス：
  • 最初の列に分析する電話番号が含まれていることを確認してください。
  • ファイルから空行を削除してください。
  • 1 行に 1 つの電話番号のみを含めてください。
  • 許可される最大ファイルサイズは 50,000 行です。

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

何らかの理由でリクエストが失敗した場合、エラーも JSON 形式で返されます。エラーにはコードと説明が含まれ、以下に詳細を示します。
CodeTypeDetails
200OKすべて期待どおりに動作しました。
400Bad request不正なリクエスト。
401Unauthorizedリクエストが受け付けられませんでした。通常は API キーが欠落しているか不正です。
422Quota reachedAPI クレジット不足のためリクエストが中断されました。（無料プラン）
429Too many requests秒あたりの許可リクエスト数に達したためリクエストが中断されました。無料プランでは 1 秒あたり 1 リクエストに制限されます。
500Internal server errorサーバー側のエラーのためリクエストを完了できませんでした。
503Service unavailableサーバーが利用できませんでした。

​
その他の注意事項

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