API ドキュメント

認証

すべてのエンドポイントでは、リクエストヘッダーに API キーが必要です。 The public product catalog does not require authentication.

http

X-API-Key: YOUR_KEY_HERE

Authorization: Bearer YOUR_KEY_HERE

キーは 51 文字です。プレフィックス zn_ に続けて 48 文字のランダム文字列が入ります。以前発行された ck_ プレフィックスのキーも引き続きご利用いただけます。

API キーはコンソールの「API センター」で確認できます。平文のキーは作成時に一度だけ表示されます。すぐに保存してください。

レスポンス形式

すべてのエンドポイントは JSON を返します。

リアルタイム応答の例

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "status": "succeeded",
  "replayed": false,
  "results": []
}

バルク応答の例

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued."
}

GET /v1/balance

残高取得

認証されたアカウントの現在の USD 残高を返します。

レスポンス例

json

{ "balance": "5.230000" }

GET /v1/products

製品リスト

公開商品カタログです。API キーは必要ありません。有効なリアルタイム商品とバルク商品、そのシリーズ、最小数量を返します。送信前に確認してください。

レスポンス例

json

{
  "data": [
    {
      "id": 101,
      "slug": "whatsapp-realtime",
      "name": "WhatsApp Number Checker",
      "name_translations": { "zh_CN": "WhatsApp 注册检测" },
      "mode": "realtime",
      "series": "phone",
      "min_phones": 1
    }
  ]
}

GET /v1/api-key

API キーの詳細

認証済みアカウントの API キーのメタデータを返します。平文のキーは返しません。

json

{
  "api_key_id": 42,
  "masked_key": "ck_••••••••••••••••••••••••••••••••••••••••••••••••",
  "last_used": "2026-09-05T10:00:00Z",
  "created_at": "2026-08-01T09:00:00Z"
}

平文のキーは作成またはローテーション時に一度だけ表示されます。このエンドポイントが返すのはマスクされた値だけです。

エラーコード

失敗時は HTTP ステータスコードと message フィールドを確認してください。

エラーレスポンス形式

json

{
  "code": "insufficient_balance",
  "message": "Insufficient balance for this submission."
}

業務エラーは常に機械可読な code を返すため、プログラムで分岐できます。パラメータ検証エラーや存在しないルートは Laravel 標準形式 { "message": "...", "errors": { ... } } を返します。送信前に入力値の検証を行ってください。

エラー

code	HTTP	説明
unauthorized	401	APIキーが未指定、無効、または無効化されています。
account_banned	403	アカウントは停止中です。サポートにご連絡ください。
invalid_realtime_request	400	リアルタイムリクエストの形式が不正です（例：country 未指定時に + 国際プレフィックスのない電話番号）。
idempotency_key_required	400	リアルタイムリクエストには Idempotency-Key ヘッダーが必要です。
invalid_idempotency_key	422	Idempotency-Key が不正です：英数字と . _ : - のみ、1〜128 文字。
idempotency_conflict	409	同じ Idempotency-Key が異なる内容のリクエストに使用されました。
request_in_progress	409	同一のリアルタイムリクエストが処理中です。少し待って再試行してください（Retry-After: 1）。
empty_input	422	アップロードされたファイルに有効な行がありません。
product_not_found	422	指定された製品スラッグが存在しないか無効です。
product_mode_not_supported	422	このエンドポイントはこの製品モードを受け付けません（リアルタイム製品を一括処理エンドポイントには送れません）。
invalid_country	422	その製品は指定された国に対応していません。
too_few_numbers	422	提出数が製品の最小件数に満たません。
too_many_numbers	422	提出数がプラットフォームの上限を超えています。
insufficient_balance	402	残高が不足しています。チャージ後に再試行してください。
realtime_disabled	403	このアカウントではリアルタイム検出が有効になっていません。
realtime_rate_limited	429	リアルタイム検出のレート制限を超えました。retry_after に従ってください。
product_pricing_unavailable	503	この製品の価格が未設定です。サポートにご連絡ください。
detection_capacity_unavailable	503	現在利用可能な検出ルートがありません。後でもう一度お試しください。
realtime_route_unavailable	503	現在利用可能なリアルタイムルートがありません。後でもう一度お試しください。
realtime_fact_cache_unavailable	503	リアルタイム検出の依存サービスが一時的に利用できません。後でお試しください。
realtime_rate_limiter_unavailable	503	レートリミッターが一時的に利用できません。後でお試しください。
not_found	404	task_id が存在しないか、別のアカウントに属しています。
result_not_ready	422	タスクが完了していないか、結果ファイルがまだ生成されていません。
result_expired	404	結果ファイルの期限が切れているか、見つからないか、利用できません。
validation_failed	422	必須項目、番号形式、ファイル種別を確認してください。
internal_error	500	サーバー内部エラーです。同じ Idempotency-Key での再試行は安全です。

レート制限

APIリクエストはAPIキーごとに、エンドポイント群単位で制限されます：

エンドポイント	制限
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	APIキーあたり 60 リクエスト / 分（IP あたり 120 / 分）
エンドポイント：POST /v1/detect · POST /v1/detect/file · POST /v1/quotes/bulk	APIキーあたり 10 リクエスト / 分（IP あたり 30 / 分）
エンドポイント：POST /v1/realtime/quote/{series} · POST /v1/realtime/check/{series} · POST /v1/realtime/detect	APIキー単位のトークンバケット：バースト60、毎秒1補充（持続約60 / 分）。アカウント単位：バースト120、毎秒2補充。IP層は180 / 分。すべてのレスポンスに X-RateLimit-Remaining ヘッダーが付きます。

制限を超えると API は Retry-After ヘッダー付きの 429 を返します（リアルタイムは retry_after フィールドもあり）。指示された秒数だけ送信を停止し、指数バックオフで再開してください。

POST /v1/realtime/check/{series}

単一識別子のリアルタイム検査

電話番号またはメールアドレスを1件同期検査します。同じ系列の複数のリアルタイム製品 ID を指定できます。一括製品の slug は使用しません。

Idempotency-Key は必須です。同じ内容とキーの再送は二重課金されず、内容を変えると 409 になります。cached=true は結果の再利用を示します。

パラメータ

フィールド	タイプ	必須	説明
series	path	はい	series：phone または email。選択したリアルタイム製品の series と一致させてください。
identifier	string	はい	識別子1件：E.164 形式の電話番号または有効なメールアドレス。
country	string	いいえ	電話番号のみ：完全な E.164 では省略可。国内形式では対応する ISO 国コードが必要です。メールでは空にします。
product_ids	array<int>	はい	リアルタイム製品 ID を1～10件指定する配列。

レスポンス例

json

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

cURL の例

bash

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":[101,102]}'

bash

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"[email protected]","country":null,"product_ids":[201]}'

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

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

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

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

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

互換用エンドポイント POST /v1/realtime/detect は旧クライアント向けに一時的に保持されています。新しい連携では /v1/realtime/check/phone または /v1/realtime/check/email を使用してください。

製品リスト · 単発（リアルタイム）

リアルタイム商品は商品 ID とシリーズで選択します。バルク商品の slug は使用しないでください。

製品名	Series	呼び出し識別子	最小件数
Amazon 電話番号チェック	`phone`	`#53`	1
Amazon メールアドレスチェック	`email`	`#54`	1
Apple ID 電話番号チェック	`phone`	`#57`	1
Apple ID メールアドレスチェック	`email`	`#58`	1
BAND 電話番号チェック	`phone`	`#60`	1
Facebook 電話番号チェック	`phone`	`#51`	1
Facebook メールアドレスチェック	`email`	`#52`	1
Instagram 電話番号チェック	`phone`	`#48`	1
Instagram メールアドレスチェック	`email`	`#49`	1
Microsoft 電話番号チェック	`phone`	`#59`	1
Telegram 電話番号チェック	`phone`	`#50`	1
Viber 電話番号チェック	`phone`	`#55`	1
WhatsApp 電話番号チェック	`phone`	`#47`	1
X 電話番号チェック	`phone`	`#61`	1

POST /v1/detect

検出を送信(配列)

電話番号またはメールアドレスの配列を送信して非同期の一括検出を開始します。費用は先に確保され、未処理分は返金されます。

最小件数は商品ごとに異なり、プラットフォーム上限は 2,000,000 件です。メールでは country を省略し、電話では必須です。

HTTP 202 Accepted

パラメータ

フィールド	タイプ	必須	説明
product	string	はい	製品 slug。製品一覧を参照してください。
country	string	電話番号では必須、メールでは省略	ISO 3166-1 2 文字の国コード。電話では必須、メールでは省略します。
phones	array	はい	電話番号またはメールアドレスの配列。最小件数は商品設定、上限は 2,000,000 件です。

レスポンス例

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "idempotent_replay": false,
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

POST /v1/detect/file

検出を送信(ファイルアップロード)

TXT または CSV をアップロードして一括検出します。1 行に電話番号またはメールアドレス 1 件、最大 50 MB。

HTTP 202 Accepted

パラメータ

Content-Type: multipart/form-data

フィールド	タイプ	必須	説明
product	string	はい	製品 slug
country	string	電話番号では必須、メールでは省略	電話用の ISO 国コード。メールでは省略します。
file	file	はい	TXT または CSV、1 行に電話番号またはメールアドレス 1 件、最大 50 MB。

レスポンス例

json

{
  "mode": "async",
  "task_id": "qH5rZ7Lp3Wm9",
  "idempotent_replay": false,
  "message": "File queued (10000 numbers). Poll GET /api/v1/tasks/qH5rZ7Lp3Wm9 for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 10000,
    "cost_deducted": 1.000000
  }
}

GET /v1/tasks/{token}

タスクステータス

ステータスが completed または failed になるまでタスクをポーリングしてください。推奨間隔: 3〜5 秒。

レスポンス例

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "YOUR_PRODUCT_SLUG",
  "country": "CN",
  "submitted": 5000,
  "prefiltered": 0,
  "deduped": 0,
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "unknown_processed": 0,
  "unknown_unprocessed": 0,
  "stage": "completed",
  "stage_seconds": 12,
  "last_progress_at": "2026-09-05T10:00:12+00:00",
  "failure_message": null,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

タスクステータス

status	説明
pending	キューに入り、リソース待ちです。
processing	検出を実行中です。
completed	完了しました。結果をダウンロードできます。
failed	実行に失敗しました。

GET /v1/tasks/{token}/result

ダウンロード URL

完了後、結果ファイルのダウンロード URL を取得します。ファイルはデフォルトで 7 日間保存されます(システム設定 result_retention_days で制御)。

レスポンス例

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "submitted": 5000,
    "prefiltered": 0,
    "deduped": 0,
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0,
    "unknown_processed": 0,
    "unknown_unprocessed": 0
  }
}

GET /v1/tasks/{token}/download

結果をダウンロード

保持期間内に、完了したタスクの結果ファイルをダウンロードします。

レスポンス例

Content-Type: application/zip (or text/csv for a single result).

このエンドポイントは JSON ではなくファイルを返します。タスクが未完了、期限切れ、利用不可、または別アカウントのものの場合は 404/422 を返します。

製品リスト · 一括（非同期）

タスク送信時に product フィールドに slug 値を使用してください。

製品名	呼び出し識別子	最小件数
Amazon 電話番号チェック	`amazonValid`	500
Amazon メールアドレスチェック	`amazonEmailValid`	1000
Apple ID 電話番号チェック	`appleidValid`	2000
Apple ID メールアドレスチェック	`appleidEmailValid`	1000
BAND 電話番号チェック	`bandValid`	500
Binance 電話番号チェック	`binanceValid`	2000
Binance メールアドレスチェック	`binanceEmailValid`	2000
CoinW 電話番号チェック	`coinwValid`	2000
CoinW メールアドレスチェック	`coinwEmailValid`	2000
Facebook 電話番号チェック	`fbValid`	500
Facebook メールアドレスチェック	`fbEmailValid`	1000
HTX 電話番号チェック	`htxValid`	1000
HTX メールアドレスチェック	`htxEmailValid`	2000
iMessage 電話番号チェック	`imessageValid`	2000
Instagram 電話番号チェック	`insValid`	500
Instagram メールアドレスチェック	`insEmailValid`	1000
KuCoin 電話番号チェック	`kucoinValid`	1000
KuCoin メールアドレスチェック	`kucoinEmailValid`	2000
LINE 年齢・性別	`lineGender`	2000
LINE 電話番号チェック	`lineValid`	2000
Linkedin プロフィール詳細	`linkedinGender`	2000
Linkedin 電話番号チェック	`linkedinValid`	2000
Microsoft 電話番号チェック	`microsoftValid`	500
RCS 対応チェック	`rcsValid`	1000
Signal 電話番号チェック	`signalValid`	2000
Snapchat 電話番号チェック	`snapchatValid`	500
Telegram プロフィール詳細	`tgGender`	500
Telegram 電話番号チェック	`tgValid`	1000
Telegram アクティビティチェック	`tgActive`	500
TikTok ユーザー名検索	`tiktokUsername`	2000
Viber 電話番号チェック	`viberValid`	1000
Viber アクティビティチェック	`viberActive`	1000
WhatsApp プロフィール詳細	`waGender`	1000
WhatsApp 電話番号チェック	`waValid`	1000
WhatsApp アクティビティ情報	`waActive`	500
X 電話番号チェック	`twitterValid`	2000
X メールアドレスチェック	`twitterEmailValid`	2000
Zalo 年齢・性別	`zaloGender`	500
Zalo 電話番号チェック	`zaloValid`	2000
インターネットアクティビティフィルター	`live-activity-filter`	2000
電話番号ステータスチェック	`phone-status-check`	2000
電源状態チェック	`phone-onoff-check`	1500
携帯機種判定	`phone-model-detection`	500
HLR ルックアップ	`hlr-lookup`	2000

完全な例

これらの cURL 例をコピーして実行してください — YOUR_KEY_HERE とパラメータを置き換えてください。

1. 残高を取得

bash

curl -X GET "https://api.zelnum.com/api/v1/balance" \
  -H "X-API-Key: YOUR_KEY_HERE"

2. 検出を送信

bash

curl -X POST "https://api.zelnum.com/api/v1/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "YOUR_PRODUCT_SLUG",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

3. ファイルをアップロード

bash

curl -X POST "https://api.zelnum.com/api/v1/detect/file" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -F "product=YOUR_PRODUCT_SLUG" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

4. タスク状態を確認

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_KEY_HERE"

5. ダウンロード URL を取得

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_KEY_HERE"