単一番号のリアルタイム検査

POST/v1/realtime/check/phone

1件の電話番号を同期検査します。1回のリクエストで複数のリアルタイム製品 ID を指定できます。一括製品の slug は使用しません。

パラメータ

フィールド	タイプ	必須	説明
`identifier`	string	はい	E.164 形式の電話番号1件（例：+8613800138000）。
`country`	string	いいえ	完全な E.164 では省略可。国内形式では対応する ISO 国コードが必要です。 — 国コード一覧
`product_ids`	array	はい	リアルタイム製品 ID を1～10件指定する配列。

検査する製品の選び方

プロダクト ID は推測せず、GET /v1/products から mode が realtime の項目の id を取得してください。バッチ製品は slug で指定するため、このエンドポイントで slug は使えません。製品一覧ページがリアルタイム ID を # 付きで表示しているのはそのためです。

製品リスト

1 回の呼び出しで、1 つの番号を最大 10 件のリアルタイム製品に対して検査できます。返るのは 1 つの request_id、results には製品ごとに 1 件、課金は項目ごとに独立するため status が partial_succeeded になることがあります。1 回の呼び出しで 11 件以上送ると拒否され、コンソールも同じ上限です。

レスポンス例

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "series": "phone",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "charged_amount": 0.004000,
  "refunded_amount": 0.000000,
  "results": [
    {
      "product_id": 47,
      "product": "wavalid-realtime",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:00Z",
      "error_code": null
    },
    {
      "product_id": 50,
      "product": "tgValid-rt",
      "result": "invalid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:01Z",
      "error_code": null
    }
  ]
}

レスポンスフィールド

フィールド	タイプ	説明
`request_id`	string (UUID)	この送信を識別する UUID。サポートへの問い合わせ時に記載してください。
`identifier`	string	チェック対象の識別子をそのまま返したもの。
`series`	string	`phone` または `email`。
`status`	string	`succeeded`、`partial_succeeded` または `failed`。課金された結果の件数から導出されます。
`request_status`	string	リクエストの内部ライフサイクル状態。
`total_reserved`	number	チェック実行前にリザーブされた金額。
`total_charged`	number	組み合わせ内のすべてのプロダクトの課金合計。
`total_refunded`	number	解決できなかった項目について返金された合計。
`charged_amount`	number	正味の課金額。常に `total_charged` と等しくなります。
`refunded_amount`	number	正味の返金額。常に `total_refunded` と等しくなります。
`replayed`	boolean	Idempotency-Key の再生によって保存済みの結果が返された場合は `true`。
`results`	array	要求したプロダクトごとに 1 件のエントリ。要求した順序で並びます。

`results[]`

フィールド	タイプ	説明
`product_id`	integer	カタログのリアルタイムプロダクト ID。
`product`	string	その ID が解決するプロダクト slug。
`result`	string	`valid`、`invalid` または `unknown`。識別子が登録されているかどうかを示します。
`cached`	boolean	判定がキャッシュから得られた場合は `true`。キャッシュヒットでも課金されます。
`billing_status`	string	`charged` または `refunded`。
`charged_amount`	number	このプロダクトに対して課金された金額。
`refunded_amount`	number	このプロダクトに対して返金された金額。
`checked_at`	string (ISO 8601)	判定が生成された時刻（UTC）。
`error_code`	string \| null	その項目を解決できなかった理由。成功した場合は `null`。

cURL の例

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","country":"CN","product_ids":[47,50]}'

課金とセマンティクス

各製品は、キャッシュ利用時もリクエスト時に固定された1回単価を使用します。valid と invalid のみ課金され、unknown、タイムアウト、混雑した項目は返金されます。

一部成功は HTTP 200 と status=partial_succeeded、全失敗は status=failed を返します。各項目の billing_status と error_code を確認してください。

Idempotency-Key は最大191バイトでユーザー単位です。タイムアウトまたは 500 の後は元の内容とキーで再試行してください。結果は既定で30日間保持されます。

error_code はプロバイダー、チャネル容量、期限、キャッシュ、同時実行保護の問題を示します。失敗項目は課金されません。

エラー

エンドポイント	意味 / 対応
`400`	番号、製品、またはキーを修正してください。事前引当はありません。
`401`	キー、アカウント状態、リアルタイム権限を確認してください。事前引当はありません。
`402`	残高不足のため、どの項目も実行されません。
`409`	Retry-After に従って再試行してください。異なる内容ではキーを再利用できません。
`429`	Retry-After の時間だけ待機してください。事前引当はありません。
`500`	結果を確認できません。新しいキーを作らず、元のキーで再試行してください。
`503`	ルート、キャッシュ、または制限機能が利用できません。後で再試行してください。