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

  1. Crea una cuenta y una clave live en el dashboard. Asigna un cupo a la clave.
  2. Guarda la clave en BB_API_KEY en tu servidor.
  3. 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

ServicioQué respondeEndpointCréditos
Verificación de emailFormato, dominio y respuesta del servidor de correo; puede quedar sin determinar.POST /api/v1/verify-email1
Análisis de IPInformación de red, ubicación estimada y coincidencias en las fuentes disponibles.POST /api/v1/verify-ip1
Teléfono · nivel 1: formato localFormato, país y tipo estimado según el plan de numeración, sin consultar al operador.POST /api/v1/verify-phone/local1
Teléfono · nivel 2: operadorLa compañía que opera el número, con el formato ya validado.POST /api/v1/verify-phone/carrier3
Teléfono · nivel 3: red móvilSi la línea está registrada y disponible al momento de consultar (HLR).POST /api/v1/verify-phone/live6
Lead combinadoSolo los datos enviados, con resultados independientes para cada uno.POST /api/v1/lead/verifysuma

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.

OpenAPI

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@latest
import { 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 rutaAutenticaciónOperación
GET /api/v1/healthPúblicoEstado mínimo de la API
POST /api/v1/suggestPúblicoSugerir corrección de un correo
GET /api/v1/domain/{domain}PúblicoConsultar atributos del dominio
POST /api/v1/demo/verifyPúblicoProbar la verificación de correo
POST /api/v1/tools/syntaxPúblicoComprobar formato de correo
POST /api/v1/tools/disposablePúblicoConsultar catálogo de descartables
GET /api/v1/tools/mx/{domain}PúblicoConsultar registros MX
GET /api/v1/tools/spf/{domain}PúblicoConsultar registro SPF
GET /api/v1/tools/dmarc/{domain}PúblicoConsultar política DMARC
GET /api/v1/tools/dkim/{domain}PúblicoConsultar un selector DKIM
GET /api/v1/tools/blacklist/{domain}PúblicoConsultar listas del dominio
GET /api/v1/tools/whois/{domain}PúblicoConsultar registro y antigüedad del dominio
POST /api/v1/credits/checkoutClave liveCrear checkout de créditos
GET /api/v1/statusPúblicoConsultar disponibilidad y fuentes
POST /api/v1/verifyClave live o públicaVerificar correo (alias anterior)
POST /api/v1/verify-emailClave live o públicaVerificar correo
POST /api/v1/verify-ipClave live o públicaAnalizar una IP
POST /api/v1/verify-phoneClave live o públicaConsultar teléfono (selección anterior)
POST /api/v1/verify-phone/localClave live o públicaValidar teléfono localmente
POST /api/v1/verify-phone/carrierClave live o públicaConsultar datos de operador
POST /api/v1/verify-phone/liveClave liveConsultar estado de red móvil
POST /api/v1/lead/verifyClave live o públicaValidar los datos enviados
POST /api/v1/phone/blacklistClave liveAñadir teléfono a la lista de bloqueo
DELETE /api/v1/phone/blacklistClave liveQuitar teléfono de la lista de bloqueo
GET /api/v1/tools/ip/{ip}PúblicoConsultar información pública de una IP
GET /api/v1/creditsClave liveConsultar saldo y cupo
POST /api/v1/bulkClave liveCrear lote de correo
GET /api/v1/bulk/{id}Clave liveConsultar estado del lote
DELETE /api/v1/bulk/{id}Clave liveSolicitar cancelación del lote
GET /api/v1/bulk/{id}/downloadClave liveObtener URL del CSV
POST /api/v1/bulk/{id}/webhookClave liveConfigurar o rotar webhook del lote

OpenAPI 3.0 · Postman · SDK Node.js · SDK Python

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.

HTTPAcción recomendada
400Corrige JSON, formato o parámetros.
401Revisa la clave y el encabezado Authorization.
402Revisa saldo, cupo y cuota inicial de teléfono.
403Revisa tipo de clave, dominio permitido y restricciones de cuenta.
409Revisa la clave de idempotencia y el estado del recurso.
429Respeta Retry-After y reduce concurrencia.
503El 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.