Lookup

Bird Lookup is the phone-number intelligence API for developers. One call returns line type, carrier, country, ported-from carrier, and a fraud signal score — all from the same data the routing layer uses to deliver your SMS.

Concept

A phone number isn't a primitive. It's a routing assertion: which carrier owns it today, what line type it sits on, whether it's been ported, whether it shows up in known fraud rings. bird.lookup.get(phone) resolves all of that in one call before you spend money on a send.

Quickstart

import { BirdClient } from "@bird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const { data, error } = await bird.lookup.get({ phone: "+14155550172" });
if (error) throw error;

console.log(data.line_type); // "mobile"
console.log(data.carrier?.name); // "T-Mobile USA"
console.log(data.fraud_score); // 12  (0 = safest, 100 = riskiest)

The shorthand form takes a bare string:

await bird.lookup.get("+14155550172");

Response shape

{
  "id": "lkp_01HZQK7E9K3M4P5R6S7T8V9W0X",
  "object": "lookup",
  "phone": "+14155550172",
  "country": "US",
  "line_type": "mobile",
  "carrier": { "name": "T-Mobile USA", "mcc": "310", "mnc": "260" },
  "ported_from": { "carrier": "AT&T Mobility", "ported_at": "2022-04-18" },
  "fraud_score": 12,
  "created_at": "2026-05-20T15:32:11Z"
}

line_type is one of: mobile, landline, voip, toll_free, unknown. ported_from is null for numbers that never ported. fraud_score is a 0–100 risk score — lower is safer; we treat anything over 70 as worth a second factor.

Common pattern — validate before SMS send

Lookup pays for itself the first time it blocks a route_unavailable SMS retry loop. Run it once per recipient at signup, cache the result for 30 days:

const { data: lookup } = await bird.lookup.get(phone);
if (!lookup || lookup.line_type === "landline") {
  return { ok: false, reason: "landline_cannot_receive_sms" };
}
if (lookup.fraud_score && lookup.fraud_score > 80) {
  return { ok: false, reason: "high_risk_recipient" };
}

await bird.sms.send({ to: phone, text: `Your code is ${code}.` });

Pricing

From $0.005 per lookup, all-in. Carrier data, ported-from history, and fraud signals are in the base price — there's no upcharge for the fraud field. See pricing for the full grid.

Webhooks

Lookup is synchronous — the response returns inside the same HTTP call — but for bulk lookup jobs (over 1,000 numbers in one batch) we emit a lookup.completed event when the job finishes:

{
  "type": "lookup.completed",
  "data": { "id": "lkp_…", "phone": "+1…", "line_type": "mobile" },
  "created_at": "2026-05-20T15:32:11Z"
}

What's not here yet

Bulk batch lookup is in private beta — talk to us if you have a list of more than 100K numbers. Email lookup (MX validation + role-account detection) lands in Q3 alongside Email Lookup as its own resource.