# `bird lookup phone-number`

## Usage

```bash
bird lookup phone-number [flags]
```

## Description

Look up a phone number

Look up what a phone number is. Returns the serving network, the issuing network, whether the number was ported, its country, and its line type, free with every call. Pass `type` to buy extra blocks: `classification` (the allocated service of the range, from an intelligence source, reported beside the free `line_type` rather than replacing it), `porting` (whether the number ever moved network, when, and its full history), `presence` (reachable on the network right now), `roaming`, `sim_swap` (when the SIM last changed), and `score` (0-100 credibility). Every requested block reports its own status, and only the ones reading `ok` are billed on top of the lookup. Nothing is sent to the number.

Build the request from flags, a JSON PhoneNumberLookupRequest body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.

## Examples

```bash
# print the body shape (no credentials needed)
bird lookup phone-number --example

# the body it prints:
```

```json
{
  "phone_number": "+31612345678",
  "type": ["classification", "presence"]
}
```

## Options

#### Request

| Name                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--body-file`       | Read the JSON request body from this file; "-" reads stdin   |
| `--example`         | Print a complete example request body, then exit             |
| `--dry-run`         | Print the resolved request without sending it, then exit     |
| `--idempotency-key` | Deduplication key; a retry with the same key won't act twice |

#### Options

| Name                | Description                                                                                                                                                                                                                                                                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--phone-number`    | The phone number to look up, in E.164 format, which is a leading +, the country calling code, then the national number.                                                                                                                                                                                                                                           |
| `--type <v1,v2,…>`  | 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. Possible values: classification, porting, presence, roaming, sim_swap, score. |
| `--response-schema` | Print the fields this command returns, then exit                                                                                                                                                                                                                                                                                                                  |