Sign inGet Started

Create a phone number lookup

POST
/v1/lookup/phone-number
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);
Response200
{
  "phone_number": "+441904123456",
  "country_code": "GB",
  "network_info": {
    "carrier_name": "BT",
    "mcc": "234",
    "mnc": "00"
  },
  "original_network_info": null,
  "flags": [],
  "line_type": "service",
  "classification": {
    "status": "ok",
    "value": "premium_rate"
  },
  "score": {
    "status": "ok",
    "value": 48
  },
  "presence": {
    "status": "ok",
    "reachable": true
  },
  "roaming": {
    "status": "unavailable"
  }
}

Returns the number's serving and issuing networks, porting state, country, and line type. The baseline fields are included in each lookup. Request additional type blocks for classification, presence, roaming, SIM-swap, porting-history, or credibility data. Each block reports its own status; only blocks with an ok status incur an additional charge.

This form keeps the number out of the URL. The URL form performs the same lookup but cannot use an idempotency key. With this form, reuse an Idempotency-Key to return the stored result without another lookup or charge.

Request Payload

phone_number
string
required

The phone number to look up, in international format: the country calling code, then the national number. The leading + is optional, and 00 works in its place, so +31612345678, 31612345678 and 0031612345678 are all the same number. A number written for dialling inside one country, with no country code, is rejected rather than guessed at.

type
array of string

Properties to add to the base lookup. Omit this field or send an empty array to request only the base lookup.

Each delivered property is billed in addition to the base lookup. A property that could not be answered is returned with its status and is not billed.

Response Payload

phone_number
string
required

The number that was looked up, in E.164 format.

country_code
nullable string

The ISO 3166-1 alpha-2 country of the number. Absent when the number belongs to no single country, as a non-geographic range does.

network_info
nullable object

The network that serves the number today. Absent when no network could be identified.

Show child attributes
original_network_info
nullable object

The network that issued the number's range. It differs from network_info when the number has been ported. Absent when the issuing network could not be identified.

Show child attributes
flags
array of string
required

Notable characteristics of the number. Empty when none apply.

line_type
string
required
classification
object

The allocated service of the number's range. Absent unless you requested the classification property.

Show child attributes
classification.status
string
required
classification.value
string

The allocated service of the range. Present only when status is ok.

presence
object

Whether the number is live on its network. Absent unless you requested the presence property.

Show child attributes
roaming
object

Whether the number is roaming. Absent unless you requested the roaming property.

Show child attributes
sim_swap
object

When the number's SIM last changed. Absent unless you requested the sim_swap property.

Show child attributes
porting
object

The number's porting record. Absent unless you requested the porting property.

Show child attributes
score
object

The number's credibility score. Absent unless you requested the score property.

Show child attributes

Continue with the documentation, guides and examples for this topic.