Documentación API — BulkChecker

Autenticación

Todos los endpoints requieren una clave API en el header.

http

X-API-Key: YOUR_API_KEY

Tu clave API está disponible en la Consola, dentro de «API Center». La clave en texto plano solo se muestra una vez al crearla; guárdala de inmediato.

Formato de Respuesta

Todos los endpoints devuelven JSON.

json

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

GET /v1/balance

Consultar Saldo

Devuelve el saldo USDT actual.

Ejemplo de Respuesta

json

{ "balance": "5.230000" }

POST /v1/detect

Detección (Array de Números)

Envía un array de números para detección. Procesado de forma asíncrona.

De 1,000 a 2,000,000 números por solicitud. Incluir código de país: +8613800138000.

Parámetros

Campo	Tipo	Requerido	Descripción
product	string	Sí	Slug del producto. Consulte la lista de productos.
country	string	Sí	Código de país ISO 3166-1 de dos letras, por ejemplo CN o US.
phones	array	Sí	Array de números, de 1,000 a 2,000,000.

Ejemplo de Respuesta

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

Detección (Subir Archivo)

Sube un archivo TXT/CSV con un número por línea, máx 50 MB.

Parámetros

Content-Type: multipart/form-data

Campo	Tipo	Requerido	Descripción
product	string	Sí	Slug del producto
country	string	Sí	Código de país ISO
file	file	Sí	Archivo TXT o CSV, un número por línea, máximo 50 MB.

Ejemplo de Respuesta

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}

Estado de Tarea

Consulta cada 3–5 segundos hasta completed o failed.

Ejemplo de Respuesta

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

Estado de Tarea

status	Descripción
pending	En cola, esperando recursos.
processing	La detección está en curso.
completed	Completado. El resultado está listo para descargar.
failed	La ejecución falló.

GET /v1/tasks/{task_id}/result

Obtener URL de Descarga

Obtén el enlace de descarga del resultado. Los archivos se conservan 7 días por defecto (configurable mediante result_retention_days).

Ejemplo de Respuesta

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

Códigos de Error

En caso de error revisa el código HTTP y el campo message.

HTTP	Error	Solución
401	Unauthenticated	Verifique que el header X-API-Key esté presente y sea válido.
402	Insufficient balance.	Saldo insuficiente. Recargue e inténtelo de nuevo.
404	Not found	task_id no existe o pertenece a otra cuenta.
422	Validación fallida	Verifique campos obligatorios, formato de números y tipo de archivo.
429	Too Many Requests	Los endpoints de detección están limitados a 10 solicitudes por minuto.

Productos

Usa el slug en el campo product al crear una tarea.

Nombre del producto	Slug
Verificador de números de Amazon	`amazonValid`
Verificador de emails de Amazon	`amazonemailValid`
Verificador de números de Apple ID	`appleidValid`
Verificador de emails de Apple ID	`appleidEmailValid`
Verificador de números de BAND	`bandValid`
Verificador de números de Binance	`binanceValid`
Verificador de emails de Binance	`binanceEmailValid`
Verificador de números de CoinW	`coinwValid`
Verificador de emails de CoinW	`coinwEmailValid`
Verificador de números de Facebook	`fbValid`
Verificador de emails de Facebook	`fbemailValid`
Consulta HLR	`hlr-lookup`
Verificador de números de HTX	`htxValid`
Verificador de emails de HTX	`htxEmailValid`
Verificador de números de iMessage	`imessageValid`
Verificador de números de Instagram	`instagram`
Verificador de emails de Instagram	`insEmailValid`
Verificador de números de KuCoin	`kucoinValid`
Verificador de emails de KuCoin	`kucoin`
Edad y género de LINE	`lineGender`
Verificador de números de LINE	`lineValid`
Number Checker	`linkednAll`
Number Checker	`linkedn`
Verificador de números de Microsoft	`microsoftValid`
Verificador de números de RCS	`RCSValid`
Verificador de números de Signal	`signalValid`
Verificador de números de Snapchat	`snapchatValid`
Perfil completo de Telegram	`tgGender`
Verificador de números de Telegram	`tgValid`
Actividad de Telegram	`tgActive`
Búsqueda de usuario de TikTok	`tkUsername`
Verificador de números de Viber	`viberValid`
Actividad de Viber	`viberActive`
Perfil completo de WhatsApp	`wsGender`
Verificador de números de WhatsApp	`wsValid`
Actividad de WhatsApp	`wsActive`
Edad y género de Zalo	`zaloGender`
Verificador de números de Zalo	`zaloValid`
Filtro de actividad de Internet	`internet-activity-filter`
Verificación de estado del número	`phone-status-check`
Detección de modelo de teléfono	`phone-model-detection`
Phone Status Check（CN）	`cnActiveNumber`

Ejemplos

Copia y ejecuta los ejemplos cURL reemplazando YOUR_API_KEY.

1. Consultar saldo

bash

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

2. Enviar detección

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. Subir archivo

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. Consultar estado de tarea

bash

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

5. Obtener URL de descarga

bash

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