Inteligencia de números telefónicos. Tipo de línea, operador, portabilidad previa, señales de fraude.
MNP-aware carrier lookup over the same wires that carry Bird's SMS and Voice traffic. One endpoint, same auth, same error envelope as every other Bird channel, because the same engineering team built them all.
import { BirdClient } from "@messagebird/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.
SDKs in every major runtime. Lookup answers in under 300ms at the median, fast enough to gate an SMS send on it.
import { BirdClient } from "@messagebird/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
A boolean valid and a reachable window: some numbers parse fine but the carrier no longer assigns them.
- 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.
Por qué creamos Lookup
Porque no deberías enterarte de que un número es fijo al ver fallar el SMS.
We were already running MNP lookups inside Bird SMS routing: we had to, to pick the cheapest carrier route in real time. Lookup is that same query, surfaced as a first-class endpoint, so you can gate signups, score risk, and forecast routing cost without sending a single SMS. Same auth, same error envelope, same webhooks as the rest of the platform.
import { BirdClient } from "@messagebird/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.
Same auth, same idempotency contract, same error envelope. Lookup is shaped like every other endpoint. The difference is that it returns data instead of dispatching a message.
Lookup.
await bird.lookup.get({
phone: "+14155550172",
});
Carrier, line type, ported-from, fraud signals: returned synchronously in under 300ms.
SMS.
await bird.sms.send({
from: "Bird",
to: "+14155550172",
text: `Your code is ${code}.`,
category: "authentication",
});
Same auth, same error envelope. Gate the send on the lookup result: drop the landlines before they cost you.