Inteligencia de números telefónicos. Tipo de línea, operador, portabilidad previa, señales de fraude.
Consulta de operador con reconocimiento MNP sobre la misma infraestructura que transporta el tráfico de SMS y Voice de Bird. Un endpoint, la misma autenticación, el mismo formato de error que cualquier otro canal de Bird — porque el mismo equipo de ingeniería los construyó todos.
import { BirdClient } from "@bird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.lookup.get({
phone: "+14155550172",
}).safe();
if (error) throw error;
console.log(data);
// → {
// phone: "+14155550172",
// line_type: "mobile",
// carrier: "T-Mobile USA",
// country: "US",
// ported_from: "AT&T Mobility",
// fraud_score: 0.07,
// valid: true,
// }5 minutos desde npm install hasta la primera consulta
Consulta un número desde el lenguaje que ya usas.
SDK en todos los runtimes principales. Lookup responde en menos de 300 ms en la mediana — lo suficientemente rápido para condicionar un envío de SMS.
import { BirdClient } from "@bird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.lookup.get({
phone: "+14155550172",
}).safe();Diez campos que de otro modo ensamblarías de tres proveedores.
Datos concretos, nombrados y auditables. Cada uno proviene de una fuente real, no de un modelo adivinando.
- 01
Detección de tipo de línea
Móvil, fijo, VoIP, gratuito, premium, buscapersonas. Decide si el SMS es siquiera posible antes de enviarlo.
- 02
Identificación de operador
Nombre del operador actual y código de país por entrada E.164. Actualizado continuamente contra los registros MNP.
- 03
Historial de portabilidad
El operador anterior desde el que se portó el número. Útil para previsión de costos de enrutamiento y heurísticas de fraude.
- 04
Formato de país y región
Devuelve formato E.164, nacional e internacional; los códigos de país y región que un enrutador necesita.
- 05
Señales de fraude
Un fraud_score de 0 a 1 por número, combinando velocidad, heurísticas de tipo de línea, indicadores de portabilidad reciente y listas de números conocidos como fraudulentos.
- 06
Validez y alcanzabilidad
Un booleano valid y una ventana reachable — algunos números se analizan correctamente, pero el operador ya no los asigna.
- 07
Consulta por lotes
Envía con POST una lista de hasta 1000 números en una sola llamada. Se aplica el mismo precio por número; te ahorras los viajes de ida y vuelta.
- 08
Precios con reconocimiento de caché
Un caché de 24 h para entradas idénticas es gratuito. Solo pagas cuando la respuesta realmente cambiaría.
- 09
Webhooks para trabajos por lotes
Para lotes grandes, suscríbete a lookup.completed y lee el archivo de resultados en lugar de mantener una conexión HTTP.
- 10
Misma autenticación, mismo formato de error
Una sola API key para Lookup, SMS, Email, WhatsApp, Voice. Un único registro de tipos de error para todos.
Why we build Lookup
Porque no deberías enterarte de que un número es fijo al ver fallar el SMS.
Ya estábamos ejecutando consultas MNP dentro del enrutamiento de SMS de Bird — teníamos que hacerlo para elegir la ruta de operador más económica en tiempo real. Lookup es esa misma consulta, expuesta como un endpoint de primera clase, para que puedas filtrar registros, evaluar riesgos y prever costos de enrutamiento sin enviar un solo SMS. Misma autenticación, mismo formato de error, mismos webhooks que el resto de la plataforma.
import { BirdClient } from "@bird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.lookup.get({
phone: "+14155550172",
}).safe();
if (error) throw error;
console.log(data);
// → {
// phone: "+14155550172",
// line_type: "mobile",
// carrier: "T-Mobile USA",
// country: "US",
// ported_from: "AT&T Mobility",
// fraud_score: 0.07,
// valid: true,
// }Cada cambio de estado es un webhook.
Payloads firmados con HMAC, protegidos contra repetición, idempotentes. Las consultas de un solo número son síncronas; las consultas por lotes se distribuyen como webhooks.
{
"type": "lookup.completed",
"id": "evt_2qB72y...",
"created_at": "2026-05-19T15:42:01.221Z",
"data": {
"lookup_id": "lkp_4hQ8m2nT",
"phone": "+14155550172",
"line_type": "mobile",
"carrier": "T-Mobile USA",
"country": "US",
"ported_from": "AT&T Mobility",
"fraud_score": 0.07,
"valid": true
}
}Programa de reintentos: 5s, 30s, 5m, 30m, 2h, 6h, 12h. Dead-letter después del último intento; cada evento en dead-letter se puede reproducir desde el dashboard o la API.
lookup.completedUna consulta (individual o por lotes) finalizó. El payload incluye la respuesta completa.lookup.failedNo se pudo realizar la consulta; el payload incluye el formato de error.
Consulta el número y luego envía.
Misma autenticación, mismo contrato de idempotencia, mismo formato de error. Lookup tiene la misma forma que cualquier otro endpoint — la diferencia es que devuelve datos en lugar de despachar un mensaje.
Lookup.
await bird.lookup.get({
phone: "+14155550172",
});Operador, tipo de línea, portabilidad previa, señales de fraude — devueltos de forma síncrona en menos de 300 ms.
SMS.
await bird.sms.send({
from: "Bird",
to: "+14155550172",
text: `Your code is ${code}.`,
});Misma autenticación, mismo formato de error. Condiciona el envío al resultado de la consulta — descarta las líneas fijas antes de que te cuesten.