Documentación de la API
Integra únicamente las comprobaciones que necesita tu producto. Correo, IP y tres niveles de teléfono, con resultados independientes y un saldo compartido.
https://api.byebouncer.com · REST · JSON · /api/v1
Primera consulta
- Crea una cuenta y una clave live en el dashboard. Asigna un cupo a la clave.
- Guarda la clave en BB_API_KEY en tu servidor.
- Elige el endpoint del servicio y solicita result_format=validation-v1.
curl --fail-with-body --max-time 30 -X POST https://api.byebouncer.com/api/v1/verify-email?result_format=validation-v1 \
-H "Authorization: Bearer $BB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"someone@example.com"}'Los valores de ejemplo son ilustrativos. Para una comprobación real utiliza datos que estés autorizado a consultar; la solicitud puede consumir créditos.
Validación de datos: resultados por comprobación
Solicita result_format=validation-v1 para recibir comprobaciones y características por dato, sin puntuaciones ni una decisión de aceptación del contacto. El cliente decide cómo utilizar cada resultado.
Cada servicio es un endpoint independiente: pedí solo el dato que necesitás y pagá solo por esa consulta. Un mismo saldo de créditos sirve para email, IP y teléfono.
Servicios, endpoints y costo en créditos
| Servicio | Qué responde | Endpoint | Créditos |
|---|---|---|---|
| Verificación de email | Formato, dominio y respuesta del servidor de correo; puede quedar sin determinar. | POST /api/v1/verify-email | 1 |
| Análisis de IP | Información de red, ubicación estimada y coincidencias en las fuentes disponibles. | POST /api/v1/verify-ip | 1 |
| Teléfono · nivel 1: formato local | Formato, país y tipo estimado según el plan de numeración, sin consultar al operador. | POST /api/v1/verify-phone/local | 1 |
| Teléfono · nivel 2: operador | La compañía que opera el número, con el formato ya validado. | POST /api/v1/verify-phone/carrier | 3 |
| Teléfono · nivel 3: red móvil | Si la línea está registrada y disponible al momento de consultar (HLR). | POST /api/v1/verify-phone/live | 6 |
| Lead combinado | Solo los datos enviados, con resultados independientes para cada uno. | POST /api/v1/lead/verify | suma |
Cada servicio aplica su política de cobro: correo consume 1 crédito por consulta cobrable, aunque el buzón quede sin determinar; IP cobra solo direcciones públicas; teléfono cobra según el producto y el resultado. En teléfono, los números inválidos o bloqueados y los errores del proveedor no se cobran. Las respuestas cobrables de caché cuestan lo mismo. /verify es un alias de /verify-email; /verify-phone decide entre local y operador según la configuración del servidor.
curl -X POST "https://api.byebouncer.com/api/v1/lead/verify?result_format=validation-v1" \
-H "Authorization: Bearer $BB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"person@example.com"}'Ejemplo ilustrativo de respuesta; example.com no se ofrece como buzón real de prueba.
{
"result_format": "validation-v1",
"execution_status": "completed",
"results": {
"email": {
"input": "person@example.com",
"deliverability": "deliverable",
"checks": {
"syntax": {
"state": "completed",
"value": true
},
"smtp": {
"state": "completed",
"value": "recipient_accepted"
}
},
"attributes": {
"name": "example.com"
}
}
}
}- Email: entregabilidad, respuesta del servidor y características como catch-all o cuenta de rol.
- Teléfono: elegí el servicio que necesitás. Validación local (formato, país y tipo estimado, 1 crédito), datos de operador (3 créditos en total) o estado de red móvil (6 créditos). Cada uno tiene su endpoint y se cobra por separado.
- IP: alcance, datos de red y resultado de cada fuente consultada. VPN/proxy no está incluido.
Correo incluye SPF, DMARC y antigüedad del dominio en attributes.domain_metadata cuando están disponibles. SPF y DMARC describen la configuración publicada para enviar correo; no autentican un mensaje ni confirman el buzón. La antigüedad se calcula desde el registro oficial del dominio, no desde la creación de la cuenta.
Los datos del dominio se consultan en segundo plano. Si todavía faltan, checks usa unavailable con reason=background_lookup_pending; esto no significa que el correo sea inválido. Puedes actualizar únicamente estos datos mediante GET /api/v1/domain/{domain}?metadata_only=1, sin repetir SMTP ni consumir créditos. El endpoint conserva su límite de consultas.
En IP, los rangos documentados de nube tienen prioridad sobre la categoría general del operador. Un perfil de ASN describe la actividad principal de una red y no demuestra que una conexión concreta sea residencial, móvil o un servidor.
Estados de ejecución: completed, not_requested, not_applicable, unavailable y failed. Una consulta completada puede devolver un hallazgo negativo; un servicio no disponible no significa que el dato sea inválido. Una respuesta HTTP 200 puede ser parcial.
La validación no acredita identidad, titularidad, consentimiento ni intención comercial. La aceptación SMTP no garantiza entrega o lectura. Un formato válido o un operador identificado no acredita conexión de la línea.
Rutas y cobro
/api/v1/verify, /api/v1/verify-email, /api/v1/verify-ip, /api/v1/verify-phone, /api/v1/verify-phone/local, /api/v1/verify-phone/carrier, /api/v1/verify-phone/live, /api/v1/lead/verify: ?result_format=validation-v1.
Cada servicio tiene su propio endpoint para que consultes solo lo que necesitás: correo (1), IP pública (1), teléfono local (1), operador (3) o red móvil (6). /verify-email es equivalente a /verify. /verify-phone/local nunca consulta al operador; /verify-phone/carrier no hace fallback a local y responde 503 phone_carrier_unavailable si el operador no está configurado. En /lead/verify podés fijar phone_mode: "local" | "carrier" para el canal de teléfono. /verify-phone mantiene su comportamiento anterior (operador si está configurado, si no local).
Solo se consultan los campos enviados. Los precios unitarios y controles de acceso se conservan. En este formato, los patrones de dígitos y VoIP no bloquean por calidad una consulta de operador; puede cobrarse una consulta que antes se omitía. Los errores, las consultas no aplicables y los débitos se rigen por la política de cada servicio.
Los trabajos de listas conservan su formato al crearse; sus CSV incluyen comprobaciones y atributos. Los trabajos e integraciones anteriores mantienen el contrato original. La oferta pública de lotes sigue siendo email; no se añade carga multicanal en este cambio.
SDK: métodos nuevos
La versión 0.4.0 de los SDK Node.js y Python agrega un método por servicio: Node.js: validate, validateEmail, validatePhoneLocal, lookupPhoneCarrier, lookupPhoneNetwork, lookupIP. Python: validate, validate_email, validate_phone_local, lookup_phone_carrier, lookup_phone_network, lookup_ip (clientes síncrono y asíncrono). Se conservan validatePhone / validate_phone con su comportamiento anterior.
Compatibilidad de la API anterior
Sin result_format se conserva la respuesta v1, incluidos los campos heredados. No interpretes esos puntajes como probabilidad de fraude ni autenticidad. Migra leyendo results y checks del formato nuevo. No hay una fecha de retirada programada: se anunciará después de revisar consumidores activos.
Autenticación y acceso
Authorization: Bearer $BB_API_KEY
Las claves bb_live_* se utilizan desde el servidor. Las claves públicas bb_pub_* están destinadas al widget, requieren cupo explícito y dominios permitidos; admiten correo, IP, teléfono local, operador y validación combinada. Una restricción de Origin controla navegadores, no acredita la identidad de otros clientes HTTP.
La red móvil, los lotes, el saldo, el checkout y la lista de bloqueo requieren una clave live. Las rutas /dashboard/* usan la sesión del panel y no forman parte de esta API de integración.
Correo · POST /api/v1/verify-email
Envía email. La respuesta reúne formato, DNS/MX, respuesta SMTP cuando está disponible y metadatos del dominio. deliverability puede ser deliverable, undeliverable o undetermined. La aceptación SMTP no garantiza entrega, lectura o existencia del buzón.
SPF y DMARC describen la configuración de envío del dominio; su antigüedad corresponde al dominio, no al buzón. Los metadatos pendientes se resuelven en segundo plano y pueden actualizarse mediante /domain/{domain}?metadata_only=1 sin repetir SMTP ni gastar créditos.
Precio: 1 crédito por consulta cobrable, también con resultado indeterminado o servido desde caché. Un límite local de admisión SMTP devuelve 429 smtp_domain_rate_limited con Retry-After; una admisión rechazada antes de consultar no se cobra.
IP · POST /api/v1/verify-ip
Envía ip. Devuelve alcance, información de red, ASN, ubicación estimada y evidencia disponible de fuentes locales. No determina identidad ni fraude. Una categoría ASN describe al operador; no prueba el tipo de conexión de cada IP.
curl --fail-with-body --max-time 30 -X POST https://api.byebouncer.com/api/v1/verify-ip?result_format=validation-v1 \
-H "Authorization: Bearer $BB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ip":"8.8.8.8"}'ip_checks permite seleccionar comprobaciones: network_data, tor, geolocation, infrastructure, anonymization_catalog, reputation_catalog, reverse_dns y dnsbl. Una fuente ausente o vencida se informa como unavailable; no_match no demuestra ausencia de VPN o proxy. No se ofrece un detector vpn_proxy.
Precio: 1 crédito por IP pública cobrable. Las direcciones privadas, reservadas o no ruteables no se cobran.
Teléfono: tres niveles independientes
Envía phone en formato internacional o añade default_country con un código ISO de dos letras para interpretar números nacionales. El país por defecto no se deduce de la IP. Los niveles se eligen por necesidad: el estado de red móvil puede solicitarse por separado y no exige comprar antes una consulta de operador.
Nivel 1 · Formato local · 1 crédito
POST /api/v1/verify-phone/local
Comprueba formato, país y tipo estimado según el plan de numeración. No consulta al operador ni a la red móvil. Un formato válido no confirma que la línea exista o esté activa. No se cobran números inválidos, no determinados o bloqueados por el cliente. live: true se rechaza con 400 para evitar añadir otro servicio a esta ruta.
curl --fail-with-body --max-time 30 -X POST https://api.byebouncer.com/api/v1/verify-phone/local?result_format=validation-v1 \
-H "Authorization: Bearer $BB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone":"+12025550123"}'Nivel 2 · Datos de operador · 3 créditos en total
POST /api/v1/verify-phone/carrier
Incluye validación de formato y los datos de operador disponibles. Cuesta 3 créditos en total, no 1 + 3. Los resultados no cobrables y los errores del proveedor no consumen créditos. Si el servicio no está configurado, devuelve 503 phone_carrier_unavailable; no lo sustituye por validación local.
curl --fail-with-body --max-time 30 -X POST https://api.byebouncer.com/api/v1/verify-phone/carrier?result_format=validation-v1 \
-H "Authorization: Bearer $BB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone":"+12025550123"}'Nivel 3 · Estado de red móvil · 6 créditos
POST /api/v1/verify-phone/live
Consulta el estado informado por la red móvil y la fecha de observación. No llama ni envía mensajes. connected, absent y unknown pueden ser respuestas de red cobrables; unknown no equivale a un error del proveedor. Un error o consulta no aplicable no se cobra. Una observación de red no garantiza que una persona responda.
curl --fail-with-body --max-time 30 -X POST https://api.byebouncer.com/api/v1/verify-phone/live?result_format=validation-v1 \
-H "Authorization: Bearer $BB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone":"+12025550123"}'Si se solicitan formato local y red móvil, el máximo es 7 créditos; operador y red móvil, 9. Las respuestas cobrables de caché mantienen el precio. Antes de la primera compra, las consultas telefónicas comparten una cuota inicial de 30 créditos.
Validación combinada · POST /api/v1/lead/verify
Envía uno o varios campos: email, ip y phone. Sólo se consultan los campos enviados. Usa phone_mode: "local" o "carrier" para elegir el servicio telefónico y live: true únicamente si también necesitas red móvil. Cada canal devuelve su resultado y se cobra por separado; una comprobación no disponible no invalida los otros resultados.
curl --fail-with-body --max-time 30 -X POST https://api.byebouncer.com/api/v1/lead/verify?result_format=validation-v1 \
-H "Authorization: Bearer $BB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone_mode":"local","email":"someone@example.com","ip":"8.8.8.8","phone":"+34612345678"}'SDK oficiales · 0.4.0
Node.js 18+ · Python 3.9+ · ESM y CommonJS; clientes Python síncrono y asíncrono.
npm install @bye_bouncer/sdk@latestimport { ByeBouncer } from "@bye_bouncer/sdk";
const client = new ByeBouncer({apiKey: process.env.BB_API_KEY});
const result = await client.validatePhoneLocal("+12025550123");
console.log(result.results.phone?.checks);
// Other independent services:
// await client.validateEmail("person@example.com");
// await client.lookupIP("8.8.8.8");
// await client.lookupPhoneCarrier("+12025550123");
// await client.lookupPhoneNetwork("+12025550123");Cada método individual hace una sola solicitud al servicio indicado. Configura timeoutMs en Node o timeout en Python. Los errores HTTP se exponen como excepciones; no se reintentan verificaciones cobrables automáticamente.
Lotes de correo
La API pública de lotes admite únicamente correo, hasta 5.000 direcciones únicas por trabajo. POST /bulk crea el trabajo; GET /bulk/{id} consulta su estado; DELETE /bulk/{id} solicita cancelación; GET /bulk/{id}/download entrega una URL firmada temporal del CSV; POST /bulk/{id}/webhook configura o rota el aviso de finalización.
curl --fail-with-body --max-time 30 -X POST https://api.byebouncer.com/api/v1/bulk?result_format=validation-v1 \
-H "Authorization: Bearer $BB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"emails":["a@example.com","b@example.com"],"filename":"clientes.csv"}'Envía Idempotency-Key con un identificador estable de la importación para reintentar su creación sin duplicarla. Reutilizar esa clave con un contenido distinto devuelve 409. Los créditos se reservan al crear el trabajo y se concilian al finalizar o cancelar. El trabajo conserva el formato de resultados solicitado al crearlo.
Si configuras un webhook, conserva su secreto al crearlo o rotarlo: no se devuelve en lecturas posteriores. Verifica X-ByeBouncer-Signature comparando HMAC-SHA256 hexadecimal del cuerpo original con el secreto del lote, usando comparación constante. Usa job_id para deduplicar avisos. Consulta OpenAPI y los README de los SDK para el contrato y los ejemplos de firma.
Dominio y herramientas públicas
GET /api/v1/domain/{domain} · POST /api/v1/suggest
La consulta de dominio describe sus características y permite actualizar sólo sus metadatos con metadata_only=1, sin verificar un buzón. /suggest recibe email y propone correcciones de escritura. Las rutas /tools/* realizan comprobaciones limitadas de formato, dominio o IP; no sustituyen la verificación completa de correo. Son públicas y están sujetas a límites de uso.
Saldo y compra de créditos
GET /api/v1/credits · POST /api/v1/credits/checkout
El saldo pertenece a la cuenta y se comparte entre claves; el cupo limita cuánto puede gastar cada una. /credits informa el remanente de la clave y wallet_balance cuando está disponible. /credits/checkout recibe el código interno pack, requiere clave live y aceptación previa de los términos vigentes. Redirige a checkout_url; los créditos se entregan sólo después del webhook de pago verificado. Comprar no amplía automáticamente los cupos existentes.
Referencia completa de endpoints
Los parámetros de ruta entre llaves deben reemplazarse y codificarse para URL. Esta lista corresponde a la API de integración; los campos, esquemas, errores y permisos detallados se definen en OpenAPI.
| Método y ruta | Autenticación | Operación |
|---|---|---|
GET /api/v1/health | Público | Estado mínimo de la API |
POST /api/v1/suggest | Público | Sugerir corrección de un correo |
GET /api/v1/domain/{domain} | Público | Consultar atributos del dominio |
POST /api/v1/demo/verify | Público | Probar la verificación de correo |
POST /api/v1/tools/syntax | Público | Comprobar formato de correo |
POST /api/v1/tools/disposable | Público | Consultar catálogo de descartables |
GET /api/v1/tools/mx/{domain} | Público | Consultar registros MX |
GET /api/v1/tools/spf/{domain} | Público | Consultar registro SPF |
GET /api/v1/tools/dmarc/{domain} | Público | Consultar política DMARC |
GET /api/v1/tools/dkim/{domain} | Público | Consultar un selector DKIM |
GET /api/v1/tools/blacklist/{domain} | Público | Consultar listas del dominio |
GET /api/v1/tools/whois/{domain} | Público | Consultar registro y antigüedad del dominio |
POST /api/v1/credits/checkout | Clave live | Crear checkout de créditos |
GET /api/v1/status | Público | Consultar disponibilidad y fuentes |
POST /api/v1/verify | Clave live o pública | Verificar correo (alias anterior) |
POST /api/v1/verify-email | Clave live o pública | Verificar correo |
POST /api/v1/verify-ip | Clave live o pública | Analizar una IP |
POST /api/v1/verify-phone | Clave live o pública | Consultar teléfono (selección anterior) |
POST /api/v1/verify-phone/local | Clave live o pública | Validar teléfono localmente |
POST /api/v1/verify-phone/carrier | Clave live o pública | Consultar datos de operador |
POST /api/v1/verify-phone/live | Clave live | Consultar estado de red móvil |
POST /api/v1/lead/verify | Clave live o pública | Validar los datos enviados |
POST /api/v1/phone/blacklist | Clave live | Añadir teléfono a la lista de bloqueo |
DELETE /api/v1/phone/blacklist | Clave live | Quitar teléfono de la lista de bloqueo |
GET /api/v1/tools/ip/{ip} | Público | Consultar información pública de una IP |
GET /api/v1/credits | Clave live | Consultar saldo y cupo |
POST /api/v1/bulk | Clave live | Crear lote de correo |
GET /api/v1/bulk/{id} | Clave live | Consultar estado del lote |
DELETE /api/v1/bulk/{id} | Clave live | Solicitar cancelación del lote |
GET /api/v1/bulk/{id}/download | Clave live | Obtener URL del CSV |
POST /api/v1/bulk/{id}/webhook | Clave live | Configurar o rotar webhook del lote |
Errores y resultados parciales
Una respuesta HTTP 200 puede tener execution_status: "partial". Lee checks y su state: completed, not_requested, not_applicable, unavailable o failed. completed describe una ejecución terminada, no un resultado favorable. unavailable no significa que el dato sea inválido.
| HTTP | Acción recomendada |
|---|---|
| 400 | Corrige JSON, formato o parámetros. |
| 401 | Revisa la clave y el encabezado Authorization. |
| 402 | Revisa saldo, cupo y cuota inicial de teléfono. |
| 403 | Revisa tipo de clave, dominio permitido y restricciones de cuenta. |
| 409 | Revisa la clave de idempotencia y el estado del recurso. |
| 429 | Respeta Retry-After y reduce concurrencia. |
| 503 | El servicio o control de admisión está temporalmente indisponible. |
Lee error, detail y reason cuando existan. No reintentes automáticamente un POST cobrable tras un timeout: el resultado y el débito pueden haberse completado. Idempotency-Key está documentado para creación de lotes, no como garantía general de verificaciones individuales.
Límites de uso
Por clave live: correo y sus alias comparten 50 solicitudes/s, 10.000/h y 100.000/día; IP y las rutas de formato/operador de teléfono, 50/s y 10.000/h. Validación combinada: 20/s. Las claves públicas tienen límites menores y un presupuesto diario compartido.
La red móvil comparte 5 solicitudes/s y 1.000/h entre ruta dedicada y consultas compuestas, con presupuestos diarios adicionales. Lotes: 10 creaciones/min y 120 lecturas/min por clave. Los controles de red y admisión pueden aplicar otros límites; consulta Retry-After y el error específico.
Estado y compatibilidad
GET /api/v1/health · GET /api/v1/status
/health es una comprobación mínima; /status informa disponibilidad y vigencia de fuentes. No confirma que una consulta particular vaya a ser concluyente. Sin result_format se conserva el contrato anterior, incluidos sus campos heredados. /verify es alias de correo; /verify-phone conserva la selección automática histórica. Para integraciones nuevas utiliza los endpoints explícitos y validation-v1.