Bird Lookup
Check the recipient before you send to them.
Check whether an email address can receive mail or find the carrier behind a phone number.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY!,
});
const answer = await bird.lookup.phoneNumber({
phone_number: "+31612345678",
type: ["porting", "score"],
});
console.log(answer.country_code, answer.line_type);
// → "NL" "mobile"
console.log(answer.network_info?.carrier_name, answer.flags);
// → "KPN" ["ported"]
// Only a block whose status is ok carries a value,
// and only that one is billed.
if (answer.score?.status === "ok") console.log(answer.score.value);
// → 84
Check an email address
Sign in to Bird to check an email address. Paste it into the Lookup form in your dashboard. You can also check addresses from your code, one API call per address.
The result helps you decide whether to send to that address. A correctly spelled address can still bounce.
See what the check tells you in email address lookup. Follow the email lookup guide to add it to your code.
5 minutes from npm install to first lookup
Look up a number or an address from the language you already use.
Typed methods in the Go, TypeScript, Python, and PHP SDKs, and bird lookup on the CLI. The dashboard runs the same two operations one at a time, which is the fastest way to see an answer before you write any code.
const answer = await bird.lookup.phoneNumber({
phone_number: "+31612345678",
type: ["classification", "score"],
});
console.log(answer.country_code, answer.line_type);
// Only a block whose status is ok carries a value, and only that one is billed.
if (answer.score?.status === "ok") console.log(answer.score.value);What a lookup answers, and what each answer costs.
Named fields from real data sources, not a model guessing. Every one of them tells you whether it was answered, and you are billed only for the ones that were.
- 01
Country and both networks
The number's country, the network serving it today, and the network that issued its range. They differ when the number has been ported.
- 02
Line-type detection
Mobile, fixed line, VoIP, toll-free, premium rate, satellite, pager, payphone, M2M, service. Decide whether SMS is even possible before you send.
- 03
The ported flag, free with the base answer
Whether the number has ever moved network arrives with every lookup. Request the porting property when you also need the dates and the full record.
- 04
Six properties on request
Name classification, porting, presence, roaming, sim_swap, or score in type. The allocated service of the range, the porting record, whether the line is live, whether it is roaming, when its SIM last changed, and a 0-100 credibility score.
- 05
A status on every property
Each block reports ok, unavailable, or inconclusive. Only ok carries a value, so you never have to inspect a response to discover it is empty.
- 06
You pay for answers, not attempts
The base lookup bills once. A property bills only when it is delivered, and a lookup that fails bills nothing at all.
- 07
One field to decide an email address on
result is valid, neutral, risky, undeliverable, or typo, with reason naming why an undeliverable address cannot receive mail.
- 08
A correction for a misspelled address
did_you_mean suggests a correction when an address looks misspelled. flags marks a role, disposable, or free-provider address, and delivery_confidence grades all of it from 0 to 100.
- 09
A retry cannot bill twice
Send an Idempotency-Key and a repeated request replays the answer you already paid for instead of buying a second one.
- 10
Same auth, same error envelope
One API key for Lookup, SMS, Email, WhatsApp, and Verify. One error registry across all of them, and a rate-limit budget of its own so a lookup never eats into your sending.
Why we build Lookup
Because you shouldn't learn a number is a landline by watching the SMS fail.
The base answer comes off the same carrier platform that routes Bird SMS and Voice, which is why asking it costs so little: we were already running the query to pick a route in real time. Lookup is that query as a first-class endpoint, so you can gate a signup, screen a lead, or route a message differently without sending anything first. Same auth, same error envelope, same idempotency contract as the rest of the platform.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY!,
});
const answer = await bird.lookup.phoneNumber({
phone_number: "+31612345678",
type: ["porting", "score"],
});
console.log(answer.country_code, answer.line_type);
// → "NL" "mobile"
console.log(answer.network_info?.carrier_name, answer.flags);
// → "KPN" ["ported"]
// Only a block whose status is ok carries a value,
// and only that one is billed.
if (answer.score?.status === "ok") console.log(answer.score.value);
// → 84
Two operations, one for each kind of recipient.
Both are a single request and a single answer. There is nothing to create, nothing to poll, and nothing to clean up afterwards.
Phone number.
Country, both networks, the ported flag, and the line type, plus any property you name in type.
Email address.
One verdict, a confidence score, the flags that explain a risky address, and a correction when it reads like a typo.
Explore Lookup
Each operation in depth. One API key, one error envelope.
Pay for the answers you get.
Priced per query: one charge per lookup, plus one for each property that comes back answered. A property we cannot answer, and a lookup that fails, cost nothing. No seat fee.
Put it into practice.
Continue with the documentation, guides and examples for this topic. Resources are in English.