API Reference

Complete email checker API reference. Endpoints, parameters, response codes for email verification and validation.

La API de BillionVerify es un servicio RESTful que proporciona potentes capacidades de verificación de correos electrónicos. Todas las solicitudes a la API deben realizarse a través de HTTPS.

URL Base

https://api.billionverify.com/v1

Especificación OpenAPI

La especificación completa de la API está disponible en formato OpenAPI 3.0:

OpenAPI YAML: https://api.billionverify.com/openapi.yaml
Documentación API Interactiva: https://api.billionverify.com/docs

Puede importar la especificación OpenAPI en herramientas como Postman, Insomnia, o usarla para generar bibliotecas cliente.

Autenticación

Todas las solicitudes a la API requieren autenticación usando un token Bearer en el encabezado Authorization:

BV-API-KEY: YOUR_API_KEY

Obtén tu clave API desde el panel de BillionVerify.

Ejemplo

curl -X POST https://api.billionverify.com/v1/verify/single \
  -H "BV-API-KEY: bv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

Límites de Tasa

Plan	Solicitudes/Hora	Solicitudes/Día
Free	100	1,000
Starter	1,000	10,000
Professional	10,000	100,000
Enterprise	Personalizado	Personalizado

La información sobre los límites de tasa se incluye en los encabezados de respuesta:

Encabezado	Descripción
`X-RateLimit-Limit`	Máximo de solicitudes permitidas
`X-RateLimit-Remaining`	Solicitudes restantes en la ventana
`X-RateLimit-Reset`	Marca de tiempo Unix cuando se restablece el límite

Cuando se excede el límite de tasa, recibirás una respuesta 429 Too Many Requests:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 3600
  }
}

Puntos Finales

Verificación de Correo Electrónico Individual

Verifica una sola dirección de correo electrónico con resultados detallados.

POST /verify/single

Solicitud

{
  "email": "user@example.com",
  "check_smtp": true
}

Parámetros

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`email`	string	Sí	-	Dirección de correo electrónico a verificar
`smtp_check`	boolean	No	`true`	Realizar verificación de buzón SMTP
`timeout`	integer	No	`5000`	Tiempo de espera de solicitud en milisegundos (máx: 30000)

Respuesta

{
  "email": "user@example.com",
  "status": "valid",
  "result": {
    "deliverable": true,
    "valid_format": true,
    "valid_domain": true,
    "valid_mx": true,
    "disposable": false,
    "role": false,
    "catchall": false,
    "free": false,
    "smtp_valid": true
  },
  "score": 0.95,
  "reason": null,
  "credits_used": 1
}

Campos de Respuesta

Campo	Tipo	Descripción
`email`	string	La dirección de correo electrónico verificada
`status`	string	Estado de verificación: `valid`, `invalid`, `unknown`, `catchall`
`result`	object	Resultados detallados de la verificación
`score`	number	Puntuación de confianza (0.0 - 1.0)
`reason`	string	Razón del estado invalid/unknown (nullable)
`credits_used`	integer	Número de créditos consumidos

Campos del Objeto Result

Campo	Tipo	Descripción
`deliverable`	boolean	Si el correo puede recibir mensajes
`valid_format`	boolean	Si el correo tiene sintaxis válida
`valid_domain`	boolean	Si el dominio existe
`valid_mx`	boolean	Si el dominio tiene registros MX
`disposable`	boolean	Si el correo es de un servicio desechable
`role`	boolean	Si el correo está basado en roles (info@, support@)
`catchall`	boolean	Si el dominio acepta todos los correos
`free`	boolean	Si el correo es de un proveedor gratuito
`smtp_valid`	boolean	Si la verificación SMTP pasó

Verificación Masiva de Correos Electrónicos

Verifica múltiples direcciones de correo electrónico de forma sincrónica. Ideal para lotes pequeños (máximo 50 correos).

POST /verify/bulk

Solicitud

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ],
  "check_smtp": true
}

Parámetros

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`emails`	array	Sí	-	Array de direcciones de correo electrónico (máx: 50)
`check_smtp`	boolean	No	`true`	Realizar verificación SMTP

Respuesta

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "results": [
      {
        "email": "user1@example.com",
        "status": "valid",
        "score": 0.95,
        "is_deliverable": true,
        "is_disposable": false,
        "is_catchall": false,
        "is_role": false,
        "is_free": false,
        "domain": "example.com",
        "smtp_check": true,
        "reason": null,
        "credits_used": 1
      }
    ],
    "total_emails": 3,
    "valid_emails": 2,
    "invalid_emails": 1,
    "credits_used": 3,
    "process_time": 2500
  }
}

Verificar Créditos

Obtén el saldo actual de créditos e información de uso.

GET /credits

Respuesta

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "account_id": "abc123",
    "api_key_id": "key_xyz",
    "api_key_name": "Default API Key",
    "credits_balance": 9500,
    "credits_consumed": 500,
    "credits_added": 10000,
    "last_updated": "2026-02-04T10:30:00Z"
  }
}

Verificación de Archivo

Sube un archivo CSV o Excel para verificación de correo asíncrona. Ideal para listas grandes.

POST /verify/file

Solicitud

curl -X POST https://api.billionverify.com/v1/verify/file \
  -H "BV-API-KEY: sk_your_api_key" \
  -F "file=@emails.csv"

Parámetros

Parámetro	Tipo	Requerido	Descripción
`file`	file	Sí	Archivo CSV o Excel (máx: 20MB, 100,000 filas)
`email_column`	string	No	Nombre de columna con correos (detección automática si no se especifica)

Formatos de Archivo Soportados

CSV (.csv)
Excel (.xlsx, .xls)
Texto (.txt) - un correo por línea

Respuesta

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "task_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "status": "pending",
    "message": "File uploaded successfully, processing started",
    "file_name": "emails.csv",
    "file_size": 45678,
    "estimated_count": 1000,
    "unique_emails": 950,
    "total_rows": 1000,
    "email_column": "email",
    "status_url": "/v1/verify/file/7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "created_at": "2026-02-04T10:30:00Z"
  }
}

Obtener Estado del Trabajo de Archivo

Verifica el estado de un trabajo de verificación de archivo.

GET /verify/file/{job_id}

Respuesta (En Progreso)

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "job_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "status": "processing",
    "file_name": "emails.csv",
    "total_emails": 1000,
    "processed_emails": 450,
    "progress_percent": 45,
    "valid_emails": 380,
    "invalid_emails": 50,
    "unknown_emails": 20,
    "created_at": "2026-02-04T10:30:00Z"
  }
}

Respuesta (Completado)

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "job_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "status": "completed",
    "file_name": "emails.csv",
    "total_emails": 1000,
    "processed_emails": 1000,
    "progress_percent": 100,
    "valid_emails": 850,
    "invalid_emails": 100,
    "unknown_emails": 30,
    "role_emails": 15,
    "catchall_emails": 5,
    "disposable_emails": 0,
    "credits_used": 970,
    "process_time_seconds": 125.5,
    "result_file_path": "results/2026/02/04/result_xxx.csv",
    "download_url": "/v1/verify/file/7143874e-21c5-43c1-96f3-2b52ea41ae6a/results",
    "created_at": "2026-02-04T10:30:00Z",
    "completed_at": "2026-02-04T10:32:05Z"
  }
}

Descargar Resultados

Descarga los resultados de verificación de un trabajo completado.

GET /verify/file/{job_id}/results

Parámetros de Consulta

Parámetro	Tipo	Predeterminado	Descripción
`valid`	boolean	-	Incluir correos válidos
`invalid`	boolean	-	Incluir correos inválidos
`catchall`	boolean	-	Incluir correos catch-all
`role`	boolean	-	Incluir correos de rol
`unknown`	boolean	-	Incluir correos desconocidos

Sin parámetros de filtro, devuelve el archivo de resultados completo. Con filtros, devuelve un CSV solo con correos coincidentes.

Ejemplo: Descargar Correos Entregables

curl -o deliverable.csv \
  "https://api.billionverify.com/v1/verify/file/{job_id}/results?valid=true&catchall=true&role=true" \
  -H "BV-API-KEY: sk_your_api_key"

Webhooks

Recibe notificaciones en tiempo real cuando los trabajos de verificación de archivos se completan.

Crear Webhook

POST /webhooks

Solicitud

{
  "url": "https://your-app.com/webhooks/billionverify",
  "events": ["file.completed", "file.failed"]
}

Parámetros

Parámetro	Tipo	Requerido	Descripción
`url`	string	Sí	URL HTTPS para recibir notificaciones webhook
`events`	array	Sí	Eventos a los que suscribirse

Respuesta

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "id": "673f3bff-81ea-4730-9cef-af1eb7f134bf",
    "url": "https://your-app.com/webhooks/billionverify",
    "events": ["file.completed", "file.failed"],
    "secret": "5c609e6893ab3b65ce8940549a030bc165762fe171e0b38f880bd570099619bf",
    "is_active": true,
    "created_at": "2026-02-04T10:30:00Z",
    "updated_at": "2026-02-04T10:30:00Z"
  }
}

Importante: El secret solo se devuelve al crear el webhook. Guárdalo de forma segura - lo necesitarás para verificar las firmas del webhook.

Listar Webhooks

GET /webhooks

Respuesta

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "webhooks": [
      {
        "id": "673f3bff-81ea-4730-9cef-af1eb7f134bf",
        "url": "https://your-app.com/webhooks/billionverify",
        "events": ["file.completed", "file.failed"],
        "is_active": true,
        "created_at": "2026-02-04T10:30:00Z",
        "updated_at": "2026-02-04T10:30:00Z"
      }
    ],
    "total": 1
  }
}

Eliminar Webhook

DELETE /webhooks/{webhook_id}

Respuesta

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "message": "Webhook deleted successfully",
    "webhook_id": "673f3bff-81ea-4730-9cef-af1eb7f134bf"
  }
}

Eventos de Webhook

Evento	Descripción
`file.completed`	Trabajo de verificación de archivo completado exitosamente
`file.failed`	Trabajo de verificación de archivo falló

Carga del Webhook

Cuando ocurre un evento, enviamos una solicitud POST a tu URL de webhook:

{
  "event": "file.completed",
  "timestamp": "2026-02-04T10:35:00Z",
  "data": {
    "job_id": "7143874e-21c5-43c1-96f3-2b52ea41ae6a",
    "file_name": "emails.csv",
    "total_emails": 1000,
    "valid_emails": 850,
    "invalid_emails": 100,
    "role_emails": 30,
    "catchall_emails": 10,
    "unknown_emails": 10,
    "disposable_emails": 0,
    "credits_used": 990,
    "process_time_seconds": 125.5,
    "result_file_path": "results/2026/02/04/result_xxx.csv",
    "download_url": ""
  }
}

Encabezados del Webhook

Encabezado	Descripción
`X-Webhook-Event`	Tipo de evento (ej. `file.completed`)
`X-Webhook-Signature`	Firma HMAC-SHA256 para verificación
`X-Webhook-Timestamp`	Marca de tiempo Unix cuando se envió el webhook
`User-Agent`	`BillionVerify-Webhook/1.0`

Verificando Firmas de Webhook

Para verificar que un webhook es de BillionVerify, calcula la firma HMAC-SHA256:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(payload)
      .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Estado de Verificación

Estado	Puntuación	Significado	Acción Recomendada
`valid`	0.9+	El correo existe y puede recibir mensajes	Seguro para enviar
`invalid`	0.1	El correo no existe o no puede recibir	Eliminar de la lista
`unknown`	0.5	No se pudo determinar la validez	Reintentar más tarde o usar con precaución
`risky`	0.4	El correo puede tener problemas de entrega	Usar con precaución, monitorear rebotes
`disposable`	0.3	El correo es de un servicio desechable	Considerar eliminar
`catchall`	0.7	El dominio acepta todos los correos (catch-all)	Monitorear rebotes
`role`	0.6	Correo basado en rol (info@, support@)	Generalmente entregable, puede tener menor engagement

Respuestas de Error

Todos los errores siguen un formato consistente:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional context (optional)"
  }
}

Códigos de Estado HTTP

Código	Descripción
`200`	Éxito
`400`	Solicitud Incorrecta - Parámetros inválidos
`401`	No Autorizado - Clave API inválida o faltante
`403`	Prohibido - Permisos insuficientes
`404`	No Encontrado - El recurso no existe
`429`	Demasiadas Solicitudes - Límite de tasa excedido
`500`	Error Interno del Servidor
`503`	Servicio No Disponible

Códigos de Error

Código	Estado HTTP	Descripción
`INVALID_API_KEY`	401	La clave API es inválida o falta
`RATE_LIMIT_EXCEEDED`	429	Demasiadas solicitudes
`INSUFFICIENT_CREDITS`	403	No hay suficientes créditos
`INVALID_EMAIL`	400	El formato del correo es inválido
`INVALID_REQUEST`	400	El cuerpo de la solicitud está mal formado
`JOB_NOT_FOUND`	404	ID de trabajo masivo no encontrado
`TIMEOUT`	504	La verificación agotó el tiempo de espera

Mejores Prácticas

1. Usa Variables de Entorno

Nunca codifiques las claves API directamente:

// Bueno
const apiKey = process.env.BV_API_KEY;

// Malo - no hagas esto
const apiKey = 'bv_live_xxx';

2. Maneja los Límites de Tasa

Implementa retroceso exponencial:

async function verifyWithRetry(email, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await verify(email);
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

3. Usa Bulk para Múltiples Correos

Para verificar más de 10 correos, usa el punto final masivo:

// Bueno - una sola llamada API
const job = await client.verifyBulk(emails);

// Malo - muchas llamadas individuales
for (const email of emails) {
  await client.verify(email);
}

4. Implementa Webhooks para Trabajos Masivos

No hagas sondeos constantes; usa webhooks:

// Enviar con webhook
const job = await client.verifyBulk(emails, {
  webhookUrl: 'https://your-app.com/webhook',
});

API Reference

Node.js

Python

Go

PHP

Java

TypeScript

Guía de Inicio Rápido

Tipos de Verificación

Guías de Integración

On this page