Telefoonnummer-intelligentie. Lijntype, provider, geporteerd-van, fraudesignalen.
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 minuten van npm install tot eerste lookup
Zoek een nummer op vanuit de taal die u al gebruikt.
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();Tien velden die u anders bij drie leveranciers zou moeten samenstellen.
Concrete datapunten, benoemd en auditeerbaar. Elk punt komt van een echte bron, niet van een model dat raadt.
- 01
Lijntype-detectie
Mobiel, vast, VoIP, gratis nummer, premium, pager. Bepaal of SMS überhaupt mogelijk is voordat u verzendt.
- 02
Provideridentificatie
Huidige providernaam en landcode per E.164-invoer. Continu bijgewerkt tegen MNP-registers.
- 03
Geporteerd-van-historie
De vorige provider waarvan het nummer is weggeporteerd. Handig voor routeringskostenprognoses en fraudeheuristieken.
- 04
Land- en regioformaat
Retourneert E.164-, nationaal en internationaal formaat; de land- en regiocodes die een router nodig heeft.
- 05
Fraudesignalen
Een fraud_score van 0-1 per nummer, gebaseerd op snelheid, lijntype-heuristieken, recente-portvlaggen en bekende-kwaadlijsten.
- 06
Validiteit en bereikbaarheid
A boolean valid and a reachable window: some numbers parse fine but the carrier no longer assigns them.
- 07
Batch-lookup
POST een lijst van maximaal 1.000 nummers in één aanroep. Dezelfde prijs per nummer geldt; u bespaart de round trips.
- 08
Cache-bewuste prijzen
Een 24-uurscache op identieke invoer is gratis. U betaalt alleen wanneer het antwoord daadwerkelijk zou verschillen.
- 09
Webhooks voor batchtaken
Abonneer u voor grote batches op lookup.completed en lees het resultaatbestand in plaats van een HTTP-verbinding open te houden.
- 10
Dezelfde auth, dezelfde error-envelope
Eén API-sleutel voor Lookup, SMS, Email, WhatsApp, Voice. Eén fouttype-register voor allemaal.
Waarom we Lookup bouwen
Want u zou niet moeten ontdekken dat een nummer een vaste lijn is door te zien dat de SMS mislukt.
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,
// }
Elke statuswijziging is een webhook.
HMAC-ondertekende payloads, replay-beschermd, idempotent. Enkele lookups zijn synchroon; batch-lookups worden als webhooks verspreid.
{
"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
}
}
Retry-schema: 5s, 30s, 5m, 30m, 2u, 6u, 12u. Dead-letter na de laatste poging; elk dead-lettered event is opnieuw afspeelbaar vanuit het dashboard of de API.
lookup.completedEen lookup (enkel of batch) is voltooid. De payload bevat de volledige response.lookup.failedLookup kon niet worden uitgevoerd; de payload bevat de error-envelope.
Zoek het nummer op en verstuur er vervolgens naartoe.
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.