# Look up a phone number (/docs/api-reference/airtime/lookup-number)

`GET /v1/airtime/number-lookup`

Describes a phone number and returns its carrier from a carrier lookup when the number is valid.

Describes the number from numbering-plan data and, for a valid number, adds carrier information from a live
carrier lookup. A number without the international shape gives 400 / 10001; a number its country does not
assign returns 200 with `isValid: false` and `carrier: null`, without a carrier lookup. Returns
503 / 10007 when the carrier lookup is unavailable. The carrier is for display only and nothing is stored; use
search to find a sellable operator.

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `phoneNumber` | query | yes | `string` | The number in international format, starting with + or 00; spaces, hyphens and parentheses are allowed. |

## Responses

### 200

OK

- `text/plain`: `NumberLookup`
- `application/json`: `NumberLookup`
- `text/json`: `NumberLookup`

### 400

Invalid partner request or model validation failure.

- `application/json`: `ErrorResponse`

### 429

Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.

- `application/json`: `ErrorResponse`

### 503

Service Unavailable

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

The full schemas are in the OpenAPI specification at /openapi.json.