Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Get a phone number lookup by URL

GET
/v1/lookup/phone-number/{number}
curl -X GET "https://us1.platform.bird.com/v1/lookup/phone-number/{number}" \
  -H "Authorization: Bearer $TOKEN"
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"
  }
}

Performs the same lookup as Create a phone number lookup, with the number in the URL. The response includes the number's serving and issuing networks, porting state, country, and line type. Repeat type to request additional blocks, such as ?type=classification&type=score; only blocks with an ok status incur an additional charge.

Because the number is in the URL, it can appear in proxies, access logs, and browser history. This form does not accept an Idempotency-Key; each retry performs and charges for another lookup.

Parameters

numberstring

The number to look up, in international format. The leading + is optional, and 00 works in its place, so 31612345678 and +31612345678 are the same number, with nothing to percent-encode. If you do send the +, percent-encode it as %2B when your client does not do that for you.

Query Parameters

typearray

An additional data block to request. Repeat the parameter for multiple blocks; each block is billed separately only when its status is ok.

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
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.

Show child attributes
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
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
presence.status
string
required
presence.reachable
boolean

Whether the number is registered on a network and able to receive traffic. A false value means the network answered and reported the number as currently unreachable. This differs from the API 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.

Show child attributes
roaming.status
string
required
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.

Show child attributes
sim_swap.status
string
required
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.

Show child attributes
porting.status
string
required
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 the period of a move without its exact 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.

Show child attributes
porting.history.occurred_at
nullable string
required

When the move was recorded, null when the record carries no date.

porting.history.action
nullable string
required

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.

Show child attributes
score.status
string
required
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. Treat it as one signal instead of a verdict. It is a composite and is not derivable from the other properties. Present only when status is ok.

Related resources

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

Get an implementation brief