Intelligence sui numeri di telefono. Tipo di linea, operatore, portabilità, segnali di frode.
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 minuti da npm install al primo lookup
Effettua il lookup di un numero nel linguaggio che già utilizzi.
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();Dieci campi che altrimenti dovresti assemblare da tre fornitori diversi.
Dati concreti, nominati e verificabili. Ognuno proviene da una fonte reale, non da un modello che indovina.
- 01
Rilevamento del tipo di linea
Mobile, fisso, VoIP, numero verde, premium, cercapersone. Decidi se l'SMS è possibile prima ancora di inviarlo.
- 02
Identificazione dell'operatore
Nome dell'operatore attuale e codice paese per input E.164. Aggiornato continuamente rispetto ai registri MNP.
- 03
Storico della portabilità
L'operatore precedente da cui il numero è stato portato. Utile per la previsione dei costi di instradamento e le euristiche antifrode.
- 04
Formato paese e regione
Restituisce il formato E.164, nazionale e internazionale; i codici paese e regione necessari al router.
- 05
Segnali di frode
Un fraud_score da 0 a 1 per numero, che combina velocità, euristiche sul tipo di linea, flag di portabilità recente e liste di numeri noti come malevoli.
- 06
Validità e raggiungibilità
A boolean valid and a reachable window: some numbers parse fine but the carrier no longer assigns them.
- 07
Lookup in batch
Invia tramite POST una lista di fino a 1.000 numeri in una singola chiamata. Si applica lo stesso prezzo per numero; risparmi i round trip.
- 08
Prezzi con gestione della cache
La cache di 24 ore su input identici è gratuita. Paghi solo quando la risposta sarebbe effettivamente diversa.
- 09
Webhook per job in batch
Per batch di grandi dimensioni, iscriviti a lookup.completed e leggi il file dei risultati invece di mantenere aperta una connessione HTTP.
- 10
Stessa autenticazione, stesso formato di errore
Una sola API key per Lookup, SMS, Email, WhatsApp, Voice. Un unico registro dei tipi di errore per tutti.
Perché abbiamo creato Lookup
Perché non dovresti scoprire che un numero è un fisso guardando l'SMS fallire.
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,
// }
Ogni cambio di stato è un webhook.
Payload firmati con HMAC, protetti dal replay, idempotenti. I lookup su singolo numero sono sincroni; i lookup in batch vengono distribuiti come webhook.
{
"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
}
}
Pianificazione dei tentativi: 5s, 30s, 5m, 30m, 2h, 6h, 12h. Dead-letter dopo l'ultimo tentativo; ogni evento in dead-letter è riproducibile dalla dashboard o dall'API.
lookup.completedUn lookup (singolo o batch) è terminato. Il payload include la risposta completa.lookup.failedIl lookup non è stato possibile; il payload include il formato di errore.
Cerca il numero, poi invia.
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.