# Search airtime by phone number (/docs/api-reference/airtime/search)

`GET /v1/airtime/search`

Searches for a phone number's operator by carrier lookup and returns it with its offers (detected flow).

Returns `{ items, pagination, details: { phoneLookup: { status, carrierName, countryCode } } }`.
`items` holds at most the detected operator with its offers. It is empty when `status` is not
`detected` or no offer remains after the filters; then let the customer choose the operator with
`GET operators?countryCode=`, using `details.phoneLookup.countryCode`. Each call makes exactly one
carrier lookup and returns at most one item, so `page` must be 1. A `phoneNumber` that is not in
international format gives 400 / 10001; a carrier lookup that fails gives 503 / 10007, retry later.

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `phoneNumber` | query | yes | `string` | The recipient's number in international format, starting with + or 00; spaces, hyphens and parentheses are allowed. |
| `valueType` | query | no | `string` | Keep only `fixed` or only `range` offers. |
| `valueCurrency` | query | no | `string` | Currency of `minValue` and `maxValue`, three letters; required with either of them. |
| `minValue` | query | no | `number` | Keep the offers whose value reaches at least this amount, in `valueCurrency`. |
| `maxValue` | query | no | `number` | Keep the offers whose value starts at or below this amount, in `valueCurrency`. |
| `minPrice` | query | no | `number` | Keep the offers whose indicative price reaches at least this amount, in the price currency. |
| `maxPrice` | query | no | `number` | Keep the offers whose indicative price starts at or below this amount, in the price currency. A filter, not the `inputs.maxPrice` limit of a purchase. |
| `currency` | query | no | `string` | Price currency, three letters in either case; the API key's currency when omitted. An unsupported code gives 400 / 10001 at `currency`, reason `NOT_SUPPORTED`. |
| `page` | query | no | `integer` | Must be 1: search returns at most one operator. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 10. |

## Responses

### 200

OK

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

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

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