Tài liệu API — BulkChecker

Xác thực

Tất cả endpoint yêu cầu khóa API trong header của request.

http

X-API-Key: YOUR_API_KEY

Khóa API có trong Bảng điều khiển tại "API Center". Khóa dạng văn bản chỉ hiển thị một lần khi tạo; hãy lưu ngay.

Định dạng phản hồi

Tất cả endpoint trả về JSON.

json

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

GET /v1/balance

Lấy số dư

Trả về số dư USDT hiện tại của tài khoản đã xác thực.

Ví dụ phản hồi

json

{ "balance": "5.230000" }

POST /v1/detect

Gửi kiểm tra (Mảng)

Gửi một mảng số điện thoại để kiểm tra. Xử lý bất đồng bộ. Chi phí được trừ trước; các số không được kiểm tra sẽ tự động hoàn tiền.

1.000 đến 2.000.000 số mỗi request. Bao gồm mã quốc gia, ví dụ +8613800138000.

Tham số

Trường	Kiểu	Bắt buộc	Mô tả
product	string	Có	Slug sản phẩm. Xem trong danh sách sản phẩm.
country	string	Có	Mã quốc gia ISO 3166-1 gồm 2 chữ cái, ví dụ CN hoặc US.
phones	array	Có	Mảng số điện thoại, từ 1.000 đến 2.000.000 số.

Ví dụ phản hồi

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

Gửi kiểm tra (Tải tệp)

Tải lên tệp TXT hoặc CSV, mỗi dòng một số, tối đa 50 MB.

Tham số

Content-Type: multipart/form-data

Trường	Kiểu	Bắt buộc	Mô tả
product	string	Có	Slug sản phẩm
country	string	Có	Mã quốc gia ISO
file	file	Có	Tệp TXT hoặc CSV, mỗi dòng một số, tối đa 50 MB.

Ví dụ phản hồi

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}

Lấy trạng thái tác vụ

Kiểm tra định kỳ cho đến khi trạng thái hoàn tất hoặc thất bại. Khoảng cách khuyến nghị: 3–5 giây.

Ví dụ phản hồi

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

Trạng thái tác vụ

status	Mô tả
pending	Đã vào hàng đợi, đang chờ tài nguyên.
processing	Tác vụ kiểm tra đang chạy.
completed	Đã hoàn tất. Kết quả sẵn sàng để tải xuống.
failed	Thực thi thất bại.

GET /v1/tasks/{task_id}/result

Lấy URL tải xuống

Sau khi hoàn tất, lấy URL tải xuống cho tệp kết quả. Mặc định tệp được giữ 7 ngày (do cài đặt hệ thống result_retention_days kiểm soát).

Ví dụ phản hồi

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

Mã lỗi

Khi lỗi, hãy kiểm tra mã trạng thái HTTP và trường message.

HTTP	Lỗi	Cách xử lý
401	Unauthenticated	Kiểm tra header X-API-Key đã được gửi và hợp lệ.
402	Insufficient balance.	Số dư tài khoản không đủ. Hãy nạp tiền rồi thử lại.
404	Not found	task_id không tồn tại hoặc thuộc tài khoản khác.
422	Xác thực dữ liệu thất bại	Kiểm tra các trường bắt buộc, định dạng số và loại tệp.
429	Too Many Requests	Endpoint kiểm tra giới hạn 10 yêu cầu mỗi phút.

Danh sách sản phẩm

Dùng giá trị slug trong trường product khi gửi tác vụ.

Tên sản phẩm	Slug
Kiểm tra số Amazon	`amazonValid`
Kiểm tra email Amazon	`amazonemailValid`
Kiểm tra số Apple ID	`appleidValid`
Kiểm tra email Apple ID	`appleidEmailValid`
Kiểm tra số BAND	`bandValid`
Kiểm tra số Binance	`binanceValid`
Kiểm tra email Binance	`binanceEmailValid`
Kiểm tra số CoinW	`coinwValid`
Kiểm tra email CoinW	`coinwEmailValid`
Kiểm tra số Facebook	`fbValid`
Kiểm tra email Facebook	`fbemailValid`
Tra cứu HLR	`hlr-lookup`
Kiểm tra số HTX	`htxValid`
Kiểm tra email HTX	`htxEmailValid`
Kiểm tra số iMessage	`imessageValid`
Kiểm tra số Instagram	`instagram`
Kiểm tra email Instagram	`insEmailValid`
Kiểm tra số KuCoin	`kucoinValid`
Kiểm tra email KuCoin	`kucoin`
Tuổi và giới tính LINE	`lineGender`
Kiểm tra số LINE	`lineValid`
Number Checker	`linkednAll`
Number Checker	`linkedn`
Kiểm tra số Microsoft	`microsoftValid`
Kiểm tra số RCS	`RCSValid`
Kiểm tra số Signal	`signalValid`
Kiểm tra số Snapchat	`snapchatValid`
Hồ sơ Telegram đầy đủ	`tgGender`
Kiểm tra số Telegram	`tgValid`
Kiểm tra hoạt động Telegram	`tgActive`
Tra cứu tên người dùng TikTok	`tkUsername`
Kiểm tra số Viber	`viberValid`
Kiểm tra hoạt động Viber	`viberActive`
Hồ sơ WhatsApp đầy đủ	`wsGender`
Kiểm tra số WhatsApp	`wsValid`
Kiểm tra hoạt động WhatsApp	`wsActive`
Tuổi và giới tính Zalo	`zaloGender`
Kiểm tra số Zalo	`zaloValid`
Lọc hoạt động Internet	`internet-activity-filter`
Kiểm tra trạng thái số điện thoại	`phone-status-check`
Kiểm tra mẫu điện thoại	`phone-model-detection`
Phone Status Check（CN）	`cnActiveNumber`

Ví dụ đầy đủ

Sao chép và chạy các ví dụ cURL này — thay YOUR_API_KEY và các tham số.

1. Lấy số dư

bash

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

2. Gửi tác vụ kiểm tra

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. Tải tệp lên

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. Kiểm tra trạng thái tác vụ

bash

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

5. Lấy URL tải xuống

bash

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