API Documentation — BulkChecker

Authentication

All endpoints require an API key in the request header.

http

X-API-Key: YOUR_API_KEY

Your API key is available in the Console under "API Center". The plaintext key is shown only once when created. Save it immediately.

Response Format

All endpoints return JSON.

json

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

GET /v1/balance

Get Balance

Returns the current USDT balance for the authenticated account.

Response Example

json

{ "balance": "5.230000" }

POST /v1/detect

Submit Detection (Array)

Submit an array of phone numbers for detection. Processed asynchronously. Cost is pre-deducted; unchecked numbers are automatically refunded.

1,000 to 2,000,000 numbers per request. Include country code, e.g. +8613800138000.

Parameters

Field	Type	Required	Description
product	string	Yes	Product slug. See the product list.
country	string	Yes	ISO 3166-1 alpha-2 country code, for example CN or US.
phones	array	Yes	Array of phone numbers, 1,000 to 2,000,000.

Response Example

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

Submit Detection (File Upload)

Upload a TXT or CSV file with one number per line, max 50 MB.

Parameters

Content-Type: multipart/form-data

Field	Type	Required	Description
product	string	Yes	Product slug
country	string	Yes	ISO country code
file	file	Yes	TXT or CSV file, one number per line, max 50 MB.

Response Example

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}

Get Task Status

Poll the task until status is completed or failed. Recommended interval: 3–5 seconds.

Response Example

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"
}

Task Status

status	Description
pending	Queued and waiting for resources.
processing	Detection is in progress.
completed	Completed. The result is ready to download.
failed	Execution failed.

GET /v1/tasks/{task_id}/result

Get Download URL

Once completed, retrieve a download URL for the result file. Files are retained for 7 days by default (controlled by the result_retention_days system setting).

Response Example

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

Error Codes

On failure, check the HTTP status code and message field.

HTTP	Error	Solution
401	Unauthenticated	Check that the X-API-Key header is present and valid.
402	Insufficient balance.	Account balance is insufficient. Top up and retry.
404	Not found	task_id does not exist or belongs to another account.
422	Validation failed	Check required fields, number format, and file type.
429	Too Many Requests	Detection endpoints are rate-limited to 10 requests per minute.

Product List

Use the slug value in the product field when submitting a task.

Product name	Slug
Amazon Number Checker	`amazonValid`
Amazon Email Checker	`amazonemailValid`
Apple ID Number Checker	`appleidValid`
Apple ID Email Checker	`appleidEmailValid`
BAND Number Checker	`bandValid`
Binance Number Checker	`binanceValid`
Binance Email Checker	`binanceEmailValid`
CoinW Number Checker	`coinwValid`
CoinW Email Checker	`coinwEmailValid`
Facebook Number Checker	`fbValid`
Facebook Email Checker	`fbemailValid`
HLR Lookup	`hlr-lookup`
HTX Number Checker	`htxValid`
HTX Email Checker	`htxEmailValid`
iMessage Number Checker	`imessageValid`
Instagram Number Checker	`instagram`
Instagram Email Checker	`insEmailValid`
KuCoin Number Checker	`kucoinValid`
KuCoin Email Checker	`kucoin`
LINE Age & Gender	`lineGender`
LINE Number Checker	`lineValid`
Number Checker	`linkednAll`
Number Checker	`linkedn`
Microsoft Number Checker	`microsoftValid`
RCS Number Checker	`RCSValid`
Signal Number Checker	`signalValid`
Snapchat Number Checker	`snapchatValid`
Telegram Full Profile	`tgGender`
Telegram Number Checker	`tgValid`
Telegram Activity Check	`tgActive`
TikTok Username Lookup	`tkUsername`
Viber Number Checker	`viberValid`
Viber Activity Check	`viberActive`
WhatsApp Full Profile	`wsGender`
WhatsApp Number Checker	`wsValid`
WhatsApp Activity Check	`wsActive`
Zalo Age & Gender	`zaloGender`
Zalo Number Checker	`zaloValid`
Internet Activity Filter	`internet-activity-filter`
Phone Status Check	`phone-status-check`
Phone Model Detection	`phone-model-detection`
Phone Status Check（CN）	`cnActiveNumber`

Full Examples

Copy and run these cURL examples — replace YOUR_API_KEY and parameters.

1. Get balance

bash

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

2. Submit detection

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. Upload file

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. Poll task status

bash

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

5. Get download URL

bash

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