<Intro>

<EndpointHeader />

<Description>

The same lookup as [Look up a phone number](/docs/api/reference/create-phone-number-lookup), with the number in the URL instead of the body.

Returns what we know about the number: which network serves it, which network issued it, whether it has been ported, its country, and what kind of line it is. Add `type` query parameters to buy extra blocks, one parameter per property: `?type=classification&type=score`. Every block you request comes back carrying a `status`, and you are billed for exactly the blocks whose status is `ok`.

Two differences from the POST form are worth knowing before you choose it. The number appears in the URL, so it will be recorded wherever request URLs are (proxies, access logs, browser history), which is why the POST form exists. And this form takes no `Idempotency-Key`, so a retry is a second lookup and is billed again.

</Description>

</Intro>

<Parameters in="path">

<Parameter name="number" type="string">

<Description>

The number to look up, in E.164 format. Percent-encode the leading plus as `%2B` if your client does not do it for you.

</Description>

</Parameter>

</Parameters>

<Parameters in="query">

<Parameter name="type" type="array">

<Description>

A property to buy for this number, on top of the free baseline. Repeat the parameter to request several. Each one is billed separately, and only when it is delivered.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="phone_number" type="string" required>

<Description>

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

</Description>

</Field>

<Field name="country_code" type="nullable string">

<Description>

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.

</Description>

</Field>

<Field name="network_info" type="nullable object">

<Description>

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

</Description>

<FieldChildren kind="response">

<Field name="carrier_name" type="nullable string" prefix="network_info.">

<Description>

The carrier's name, absent when the carrier could not be identified.

</Description>

</Field>

<Field name="mcc" type="nullable string" prefix="network_info.">

<Description>

The mobile country code, absent for a network that has none or could not be identified.

</Description>

</Field>

<Field name="mnc" type="nullable string" prefix="network_info.">

<Description>

The mobile network code, absent for a network that has none or could not be identified.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="original_network_info" type="nullable object">

<Description>

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.

</Description>

<FieldChildren kind="response">

<Field name="carrier_name" type="nullable string" prefix="original_network_info.">

<Description>

The carrier's name, absent when the carrier could not be identified.

</Description>

</Field>

<Field name="mcc" type="nullable string" prefix="original_network_info.">

<Description>

The mobile country code, absent for a network that has none or could not be identified.

</Description>

</Field>

<Field name="mnc" type="nullable string" prefix="original_network_info.">

<Description>

The mobile network code, absent for a network that has none or could not be identified.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="flags" type="array of string" required>

<Description>

Notable characteristics of the number. Empty when none apply.

</Description>

</Field>

<Field name="line_type" type="object" required />

<Field name="classification" type="object">

<Description>

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

</Description>

<FieldChildren kind="response">

<Field name="status" type="object" prefix="classification." required />

<Field name="value" type="object" prefix="classification.">

<Description>

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

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="presence" type="object">

<Description>

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

</Description>

<FieldChildren kind="response">

<Field name="status" type="object" prefix="presence." required />

<Field name="reachable" type="boolean" prefix="presence.">

<Description>

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

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="roaming" type="object">

<Description>

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

</Description>

<FieldChildren kind="response">

<Field name="status" type="object" prefix="roaming." required />

<Field name="is_roaming" type="boolean" prefix="roaming.">

<Description>

Whether the number is currently roaming outside its home network. Present only when `status` is `ok`.

</Description>

</Field>

<Field name="mcc" type="nullable string" prefix="roaming.">

<Description>

The mobile country code of the visited network. Absent when the number is not roaming or the visited network is not reported.

</Description>

</Field>

<Field name="mnc" type="nullable string" prefix="roaming.">

<Description>

The mobile network code of the visited network. Absent when the number is not roaming or the visited network is not reported.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="sim_swap" type="object">

<Description>

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

</Description>

<FieldChildren kind="response">

<Field name="status" type="object" prefix="sim_swap." required />

<Field name="last_swapped_at" type="nullable string" prefix="sim_swap.">

<Description>

When the SIM was last changed. Absent when only a recency band is known.

</Description>

</Field>

<Field name="min_days" type="nullable integer" prefix="sim_swap.">

<Description>

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.

</Description>

</Field>

<Field name="max_days" type="nullable integer" prefix="sim_swap.">

<Description>

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.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="porting" type="object">

<Description>

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

</Description>

<FieldChildren kind="response">

<Field name="status" type="object" prefix="porting." required />

<Field name="ported" type="boolean" prefix="porting.">

<Description>

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

</Description>

</Field>

<Field name="last_ported_at" type="nullable string" prefix="porting.">

<Description>

When the number last moved network. Absent when it has never ported or when no date is on record.

</Description>

</Field>

<Field name="last_ported_at_is_approximate" type="boolean" prefix="porting.">

<Description>

Whether `last_ported_at` is an approximation. Some registries record only the period a move happened in, not the day.

</Description>

</Field>

<Field name="history" type="array of object" prefix="porting.">

<Description>

Every move on record, oldest first. Absent when the number has never ported or when its registry publishes no history.

</Description>

<FieldChildren kind="response">

<Field name="occurred_at" type="nullable string" prefix="porting.history." required>

<Description>

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

</Description>

</Field>

<Field name="action" type="nullable string" prefix="porting.history." required>

<Description>

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.

</Description>

</Field>

</FieldChildren>

</Field>

</FieldChildren>

</Field>

<Field name="score" type="object">

<Description>

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

</Description>

<FieldChildren kind="response">

<Field name="status" type="object" prefix="score." required />

<Field name="value" type="integer" prefix="score.">

<Description>

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

</Description>

</Field>

</FieldChildren>

</Field>

</Payload>