Documentation
Sign inGet started

Look up a phone number

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);
Returns what we know about a phone number: which network serves it, which network issued it, whether it has been ported, its country, and what kind of line it is. That baseline is included with every lookup.
Use type to buy more. Each value adds a block to the answer: how the number is classified, whether it is live on the network right now, whether it is roaming, when its SIM last changed, its porting record, or a credibility score. Omit type and the response is the baseline alone, and no intelligence provider is contacted.
Every block you request comes back carrying a status, so a partial answer is visible rather than silent, and you are billed for exactly the blocks whose status is ok.
Send the number in the body rather than the URL when you would rather it did not appear in request logs or browser history. Look up a phone number by URL is the same lookup with the number in the path.
Send an Idempotency-Key and a retried request returns the stored answer instead of looking the number up and charging again. Without one, every attempt is a new lookup and is billed.
Corps de la requête
phone_number
string
obligatoire
The phone number to look up, in E.164 format, which is a leading +, the country calling code, then the national number.
type
array of string
The paid properties to enrich the answer with. Omit it, or send an empty array, to get the free baseline and make no vendor call.
Each delivered property is billed on top of the lookup itself. A property that could not be answered is reported in properties and is not billed.
Contenu de la réponse
phone_number
string
obligatoire
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.
Afficher les attributs enfants
network_info.carrier_name
nullable string
The carrier's name, absent when the carrier could not be identified.
network_info.mcc
nullable string
The mobile country code, absent for a network that has none or could not be identified.
network_info.mnc
nullable string
The mobile network code, absent for a network that has none or could not be identified.
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.
Afficher les attributs enfants
original_network_info.carrier_name
nullable string
The carrier's name, absent when the carrier could not be identified.
original_network_info.mcc
nullable string
The mobile country code, absent for a network that has none or could not be identified.
original_network_info.mnc
nullable string
The mobile network code, absent for a network that has none or could not be identified.
flags
array of string
obligatoire
Notable characteristics of the number. Empty when none apply.
line_type
object
obligatoire
classification
object
The allocated service of the number's range. Absent unless you requested the classification property.
Afficher les attributs enfants
classification.status
object
obligatoire
classification.value
object
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.
Afficher les attributs enfants
presence.status
object
obligatoire
presence.reachable
boolean
Whether the number is registered on a network and able to receive traffic. False means the network answered and reported the number as not currently reachable, which is different from us being unable to find out. Present only when status is ok.
roaming
object
Whether the number is roaming. Absent unless you requested the roaming property.
Afficher les attributs enfants
roaming.status
object
obligatoire
roaming.is_roaming
boolean
Whether the number is currently roaming outside its home network. Present only when status is ok.
roaming.mcc
nullable string
The mobile country code of the visited network. Absent when the number is not roaming or the visited network is not reported.
roaming.mnc
nullable string
The mobile network code of the visited network. Absent when the number is not roaming or the visited network is not reported.
sim_swap
object
When the number's SIM last changed. Absent unless you requested the sim_swap property.
Afficher les attributs enfants
sim_swap.status
object
obligatoire
sim_swap.last_swapped_at
nullable string
When the SIM was last changed. Absent when only a recency band is known.
sim_swap.min_days
nullable integer
The lower bound, in days, of how long ago the SIM was last changed. Networks that do not release an exact date report a band instead; absent when no lower bound is known.
sim_swap.max_days
nullable integer
The upper bound, in days, of how long ago the SIM was last changed. Absent when no upper bound is known; with a lower bound present, that means the change was at least min_days ago.
porting
object
The number's porting record. Absent unless you requested the porting property.
Afficher les attributs enfants
porting.status
object
obligatoire
porting.ported
boolean
Whether the number has ever moved network. False is a positive finding rather than a lack of one: the registry was consulted and holds no move for this number. Present only when status is ok.
porting.last_ported_at
nullable string
When the number last moved network. Absent when it has never ported or when no date is on record.
porting.last_ported_at_is_approximate
boolean
Whether last_ported_at is an approximation. Some registries record only the period a move happened in, not the day.
porting.history
array of object
Every move on record, oldest first. Absent when the number has never ported or when its registry publishes no history.
Afficher les attributs enfants
porting.history.occurred_at
nullable string
obligatoire
When the move was recorded, null when the record carries no date.
porting.history.action
nullable string
obligatoire
What the record describes, as the number's registry reports it. Registries use their own short codes rather than a shared vocabulary, so treat this as a label to display rather than a value to branch on.
score
object
The number's credibility score. Absent unless you requested the score property.
Afficher les attributs enfants
score.status
object
obligatoire
score.value
integer
Credibility from 0 (low) to 100 (high). A low score means the number looks less credible than a typical subscriber line in the same range; it is a signal to weigh, not a verdict. It is a composite and is not derivable from the other properties. Present only when status is ok.