# Create a phone number lookup

`POST /v1/lookup/phone-number`

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](/docs/api/reference/get-phone-number-lookup) 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.

## Code samples

**TypeScript**

```ts
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);
```

Examples: [TypeScript](/docs/api/reference/create-phone-number-lookup.ts.md) · [Python](/docs/api/reference/create-phone-number-lookup.py.md) · [Go](/docs/api/reference/create-phone-number-lookup.go.md) · [PHP](/docs/api/reference/create-phone-number-lookup.php.md) · [CLI](/docs/api/reference/create-phone-number-lookup.cli.md) · [MCP](/docs/api/reference/create-phone-number-lookup.mcp.md) · [cURL](/docs/api/reference/create-phone-number-lookup.curl.md)

## Example response `200`

```json
{
  "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"
  }
}
```

## Request body

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

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

- [Phone number lookup: check a number before you send](/learn/lookup/phone-number-lookup-check-a-number-before-you-send) (video)
- [Lookup](/lookup-api) (product)
- [Lookup overview](/docs/guides/lookup/overview) (docs)

[Get an implementation brief](/learn/workspace?topic=lookup)