Intelligence sui numeri di telefono. Tipo di linea, operatore, portabilità, segnali di frode.
Lookup dell'operatore con supporto MNP sulla stessa rete che trasporta il traffico SMS e Voice di Bird. Un unico endpoint, stessa autenticazione, stesso formato di errore di ogni altro canale Bird — perché lo stesso team di ingegneri li ha costruiti tutti.
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 minuti da npm install al primo lookup
Effettua il lookup di un numero nel linguaggio che già utilizzi.
SDK per ogni runtime principale. Lookup risponde in meno di 300 ms al percentile mediano — abbastanza veloce da condizionare l'invio di un 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();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à
Un booleano valid e una finestra reachable — alcuni numeri sono sintatticamente corretti ma l'operatore non li assegna più.
- 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.
Why we build Lookup
Perché non dovresti scoprire che un numero è un fisso guardando l'SMS fallire.
Stavamo già eseguendo lookup MNP all'interno del routing SMS di Bird — dovevamo farlo, per scegliere la rotta dell'operatore più economica in tempo reale. Lookup è quella stessa query, esposta come endpoint di prima classe, così puoi filtrare le registrazioni, valutare il rischio e prevedere i costi di instradamento senza inviare un singolo SMS. Stessa autenticazione, stesso formato di errore, stessi webhook del resto della piattaforma.
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,
// }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.
Stessa autenticazione, stesso contratto di idempotenza, stesso formato di errore. Lookup ha la stessa struttura di ogni altro endpoint — la differenza è che restituisce dati invece di inviare un messaggio.
Lookup.
await bird.lookup.get({
phone: "+14155550172",
});Operatore, tipo di linea, portabilità, segnali di frode — restituiti in modo sincrono in meno di 300 ms.
SMS.
await bird.sms.send({
from: "Bird",
to: "+14155550172",
text: `Your code is ${code}.`,
});Stessa autenticazione, stesso formato di errore. Condiziona l'invio al risultato del lookup — scarta i numeri fissi prima che ti costino.