API ドキュメント

認証

すべてのエンドポイントでは、リクエストヘッダーに API キーが必要です。

http

X-API-Key: YOUR_API_KEY

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

レスポンス形式

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

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued.",
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

GET /v1/balance

残高取得

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

レスポンス例

json

{ "balance": "5.230000" }

POST /v1/detect

検出を送信(配列)

電話番号の配列を検出のために送信します。非同期で処理されます。コストは事前控除され、未チェック番号は自動返金されます。

リクエストあたり 1,000 〜 2,000,000 件。国コードを含めてください。例: +8613800138000。

パラメータ

フィールド	タイプ	必須	説明
product	string	はい	製品 slug。製品一覧を参照してください。
country	string	はい	ISO 3166-1 の2文字国コード。例: CN、US。
phones	array	はい	電話番号の配列。1,000〜2,000,000 件。

レスポンス例

json

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

POST /v1/detect/file

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

1 行 1 番号の TXT または CSV ファイルをアップロード、最大 50 MB。

パラメータ

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",
  "message": "File queued (10000 numbers). Poll GET /api/v1/tasks/qH5rZ7Lp3Wm9 for progress.",
  "summary": {
    "total": 10000,
    "cost_deducted": 1.000000
  }
}

GET /v1/tasks/{task_id}

タスクステータス

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

レスポンス例

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "whatsapp-active",
  "country": "CN",
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "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/{task_id}/result

ダウンロード URL

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

レスポンス例

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0
  }
}

エラーコード

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

HTTP	エラー	解決策
401	Unauthenticated	X-API-Key ヘッダーがあり、有効であることを確認してください。
402	Insufficient balance.	残高が不足しています。チャージして再試行してください。
404	Not found	task_id が存在しないか、別のアカウントに属しています。
422	バリデーションに失敗しました	必須項目、番号形式、ファイル種別を確認してください。
429	Too Many Requests	検出 endpoint は 1分あたり 10 リクエストに制限されています。

製品リスト

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

製品名	Slug
Amazon 番号チェッカー	`amazonValid`
Amazon メールチェッカー	`amazonemailValid`
Apple ID 番号チェッカー	`appleidValid`
Apple ID メールチェッカー	`appleidEmailValid`
BAND 番号チェッカー	`bandValid`
Binance 番号チェッカー	`binanceValid`
Binance メールチェッカー	`binanceEmailValid`
CoinW 番号チェッカー	`coinwValid`
CoinW メールチェッカー	`coinwEmailValid`
Facebook 番号チェッカー	`fbValid`
Facebook メールチェッカー	`fbemailValid`
HLR ルックアップ	`hlr-lookup`
HTX 番号チェッカー	`htxValid`
HTX メールチェッカー	`htxEmailValid`
iMessage 番号チェッカー	`imessageValid`
Instagram 番号チェッカー	`instagram`
Instagram メールチェッカー	`insEmailValid`
KuCoin 番号チェッカー	`kucoinValid`
KuCoin メールチェッカー	`kucoin`
LINE 年齢・性別	`lineGender`
LINE 番号チェッカー	`lineValid`
Number Checker	`linkednAll`
Number Checker	`linkedn`
Microsoft 番号チェッカー	`microsoftValid`
RCS 番号チェッカー	`RCSValid`
Signal 番号チェッカー	`signalValid`
Snapchat 番号チェッカー	`snapchatValid`
Telegram フルプロフィール	`tgGender`
Telegram 番号チェッカー	`tgValid`
Telegram アクティビティチェック	`tgActive`
TikTok ユーザー名検索	`tkUsername`
Viber 番号チェッカー	`viberValid`
Viber アクティビティチェック	`viberActive`
WhatsApp フルプロフィール	`wsGender`
WhatsApp 番号チェッカー	`wsValid`
WhatsApp アクティビティチェック	`wsActive`
Zalo 年齢・性別	`zaloGender`
Zalo 番号チェッカー	`zaloValid`
インターネットアクティビティフィルター	`internet-activity-filter`
番号ステータスチェック	`phone-status-check`
携帯機種判定	`phone-model-detection`
Phone Status Check（CN）	`cnActiveNumber`

完全な例

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

1. 残高を取得

bash

curl -X GET "https://api.bulkchecker.io/api/v1/balance" \
  -H "X-API-Key: YOUR_API_KEY"

2. 検出を送信

bash

curl -X POST "https://api.bulkchecker.io/api/v1/detect" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "whatsapp-active",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

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

bash

curl -X POST "https://api.bulkchecker.io/api/v1/detect/file" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "product=whatsapp-active" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

4. タスク状態を確認

bash

curl -X GET "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_API_KEY"

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

bash

curl -X GET "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_API_KEY"