---
title: "Get a phone number lookup by URL"
method: GET
path: "/v1/lookup/phone-number/{number}"
tags: ["lookup"]
---

# Get a phone number lookup by URL

`GET /v1/lookup/phone-number/{number}`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/lookup/phone-number/{number}`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Performs the same lookup as [Create a phone number lookup](/docs/api/reference/create-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.

## Path parameters

- `number` string, required

## Query parameters

- `type` LookupProperty[]

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

Available network and number-intelligence information.

- PhoneNumberLookup: Information about a phone number. The number, its flags, and its line type are included in the base lookup and are always present. The country and two networks are present when identified. Each property you request through `type` is returned in a block with the same name and its own `status`. A property you did not request is absent. A property that could not be answered is present with only its `status`. Each requested property is billed only when its status is `ok`. Fields with no value are omitted rather than returned as `null`.
  - `phone_number` string, required: The number that was looked up, in E.164 format.
  - `country_code` string: ISO 3166-1 alpha-2 country code.
  - `network_info` LookupNetworkInfo: The network a number belongs to.
    - `carrier_name` string, nullable: The carrier's name, absent when the carrier could not be identified.
    - `mcc` string, nullable: The mobile country code, absent for a network that has none or could not be identified.
    - `mnc` string, nullable: The mobile network code, absent for a network that has none or could not be identified.
  - `original_network_info` LookupNetworkInfo: The network a number belongs to.
    - `carrier_name` string, nullable: The carrier's name, absent when the carrier could not be identified.
    - `mcc` string, nullable: The mobile country code, absent for a network that has none or could not be identified.
    - `mnc` string, nullable: The mobile network code, absent for a network that has none or could not be identified.
  - `flags` LookupFlag[], required: Notable characteristics of the number. Empty when none apply.
  - `line_type` 'mobile' | 'fixed_line' | 'voip' | 'toll_free' | 'premium_rate' | 'satellite' | 'pager' | 'payphone' | 'm2m' | 'service' | 'other' | 'unknown', required: What kind of line the number is, as reported by the carrier platform. This is included in every base lookup, regardless of which properties you request. - `unknown`: the carrier platform holds no classification for the range. - `other`: it holds a classification with no equivalent here. - `m2m`: a range reserved for machine-to-machine traffic, belonging to no individual subscriber. For the allocated service of the range at finer precision, request the `classification` property. That answers from a different source, with its own wider vocabulary, and is reported separately so you can always tell the two apart.
  - `classification` LookupClassification: The allocated service of the number's range. Returned when you request the `classification` property. This sits beside `line_type` rather than replacing it, so you can always see which source answered. The `line_type` property is included in the base lookup and comes from the carrier platform. The `classification` property is separately billed and comes from an intelligence source.
    - `status` string, required: How a requested property resolved. - `ok`: the property was answered and its value is in the response. - `unavailable`: no answer arrived, so the property adds nothing: its block is `null`, or for `classification`, `line_type` retains the value from the base lookup. The property is not billed. - `inconclusive`: an answer arrived but does not resolve the property, either because the number is outside the coverage of the data behind it or because the source returned a value this property does not report. It is a real answer rather than a missing one, and it is not billed either. Open enum: further statuses may be added over time, so treat an unrecognized value as a future one rather than an error. Only `ok` carries a value and only `ok` is billed, so branching on `ok` and treating everything else as "not answered" stays correct however the vocabulary grows.
    - `value` 'mobile' | 'fixed_line' | 'fixed_line_or_mobile' | 'voip' | 'toll_free' | 'premium_rate' | 'shared_cost' | 'local_rate' | 'national_rate' | 'personal_number' | 'universal_access' | 'satellite' | 'pager' | 'payphone' | 'm2m' | 'isp' | 'vpn' | 'voice_mail' | 'calling_cards' | 'short_codes' | 'service' | 'other': The allocated service of the number's range, at the precision the intelligence source publishes it. This is a finer vocabulary than `line_type`, which reports what the carrier platform alone can tell. Some values have no carrier equivalent. For example, a number the carrier calls `service` may be classified as `premium_rate`, `shared_cost`, `universal_access`, or a voicemail platform. Where the fields overlap, they remain independent results rather than one refining the other. Three values in particular have no carrier-side concept at all: - `m2m` is a range reserved for machine-to-machine traffic, belonging to no individual subscriber. - `national_rate` is a non-geographic landline number charged above the local rate. - `fixed_line_or_mobile` is a range a country allocates so a number can port between the two.
  - `presence` LookupPresence: Whether the number is live on its network right now. Returned when you request the `presence` property. The result reflects a real-time query to the network where the number is registered.
    - `status` string, required: How a requested property resolved. - `ok`: the property was answered and its value is in the response. - `unavailable`: no answer arrived, so the property adds nothing: its block is `null`, or for `classification`, `line_type` retains the value from the base lookup. The property is not billed. - `inconclusive`: an answer arrived but does not resolve the property, either because the number is outside the coverage of the data behind it or because the source returned a value this property does not report. It is a real answer rather than a missing one, and it is not billed either. Open enum: further statuses may be added over time, so treat an unrecognized value as a future one rather than an error. Only `ok` carries a value and only `ok` is billed, so branching on `ok` and treating everything else as "not answered" stays correct however the vocabulary grows.
    - `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` LookupRoaming: Whether the number is roaming, and on which network. Returned when you request the `roaming` property.
    - `status` string, required: How a requested property resolved. - `ok`: the property was answered and its value is in the response. - `unavailable`: no answer arrived, so the property adds nothing: its block is `null`, or for `classification`, `line_type` retains the value from the base lookup. The property is not billed. - `inconclusive`: an answer arrived but does not resolve the property, either because the number is outside the coverage of the data behind it or because the source returned a value this property does not report. It is a real answer rather than a missing one, and it is not billed either. Open enum: further statuses may be added over time, so treat an unrecognized value as a future one rather than an error. Only `ok` carries a value and only `ok` is billed, so branching on `ok` and treating everything else as "not answered" stays correct however the vocabulary grows.
    - `is_roaming` boolean: Whether the number is currently roaming outside its home network. Present only when `status` is `ok`.
    - `mcc` string, nullable: The mobile country code of the visited network. Absent when the number is not roaming or the visited network is not reported.
    - `mnc` string, nullable: The mobile network code of the visited network. Absent when the number is not roaming or the visited network is not reported.
  - `sim_swap` LookupSimSwap: When the number's SIM last changed. Returned when you request the `sim_swap` property.
    - `status` string, required: How a requested property resolved. - `ok`: the property was answered and its value is in the response. - `unavailable`: no answer arrived, so the property adds nothing: its block is `null`, or for `classification`, `line_type` retains the value from the base lookup. The property is not billed. - `inconclusive`: an answer arrived but does not resolve the property, either because the number is outside the coverage of the data behind it or because the source returned a value this property does not report. It is a real answer rather than a missing one, and it is not billed either. Open enum: further statuses may be added over time, so treat an unrecognized value as a future one rather than an error. Only `ok` carries a value and only `ok` is billed, so branching on `ok` and treating everything else as "not answered" stays correct however the vocabulary grows.
    - `last_swapped_at` string, date-time, nullable: When the SIM was last changed. Absent when only a recency band is known.
    - `min_days` integer, nullable: 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.
    - `max_days` integer, nullable: 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` LookupPorting: Whether the number has ever moved network, when it last did, and its full porting record. Returned when you request the `porting` property. The base lookup only reports whether the number has ever ported, through the `ported` flag.
    - `status` string, required: How a requested property resolved. - `ok`: the property was answered and its value is in the response. - `unavailable`: no answer arrived, so the property adds nothing: its block is `null`, or for `classification`, `line_type` retains the value from the base lookup. The property is not billed. - `inconclusive`: an answer arrived but does not resolve the property, either because the number is outside the coverage of the data behind it or because the source returned a value this property does not report. It is a real answer rather than a missing one, and it is not billed either. Open enum: further statuses may be added over time, so treat an unrecognized value as a future one rather than an error. Only `ok` carries a value and only `ok` is billed, so branching on `ok` and treating everything else as "not answered" stays correct however the vocabulary grows.
    - `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`.
    - `last_ported_at` string, date-time, nullable: When the number last moved network. Absent when it has never ported or when no date is on record.
    - `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.
    - `history` LookupPortingEvent[]: Every move on record, oldest first. Absent when the number has never ported or when its registry publishes no history.
      - `occurred_at` string, date-time, nullable, required: When the move was recorded, `null` when the record carries no date.
      - `action` string, nullable, 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` LookupScore: A credibility score for the number. Returned when you request the `score` property.
    - `status` string, required: How a requested property resolved. - `ok`: the property was answered and its value is in the response. - `unavailable`: no answer arrived, so the property adds nothing: its block is `null`, or for `classification`, `line_type` retains the value from the base lookup. The property is not billed. - `inconclusive`: an answer arrived but does not resolve the property, either because the number is outside the coverage of the data behind it or because the source returned a value this property does not report. It is a real answer rather than a missing one, and it is not billed either. Open enum: further statuses may be added over time, so treat an unrecognized value as a future one rather than an error. Only `ok` carries a value and only `ok` is billed, so branching on `ok` and treating everything else as "not answered" stays correct however the vocabulary grows.
    - `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`.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `402`: Insufficient balance
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)