# Search eSIM plans (/docs/api-reference/esims/search)

`GET /v1/esims/search`

Searches eSIM destinations and returns them with their plans, one page at a time.

Returns `{ items, pagination }`. `countryCode` keeps the destinations whose coverage includes that
country, so local, regional and global destinations can match; `category` and `region` select
destinations, and `validityDays` and `isUnlimited` select plans within them. Pages count destinations
with an orderable plan. With `iccid` it returns the plans that can top up that eSIM instead, under its
destination, and takes no filter other than `currency` (400 / 10001, `NOT_ALLOWED`); an unknown or
foreign ICCID gives 404 / 10004. Prices are indicative, in `currency`.

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `countryCode` | query | no | `string` | Optional ISO 3166-1 alpha-2 country, in either case: keeps the destinations whose coverage includes it, regional and global ones too. A blank value is rejected. |
| `category` | query | no | `string` | Keep `local`, `regional` or `global` destinations. |
| `region` | query | no | `string` | Keep the destinations of this region, in display or slug form, for example `North America` or `north-america`. |
| `validityDays` | query | no | `integer` | Keep the plans valid for exactly this many days; at least 1. |
| `isUnlimited` | query | no | `boolean` | Keep the unlimited (`true`) or the limited (`false`) plans. |
| `iccid` | query | no | `string` | Top-up search: the ICCID (18 to 22 digits) of your eSIM to list the plans that can top it up. No other filter than `currency` is allowed with it. |
| `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` | Page number, from 1; default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 10. |

## Responses

### 200

OK

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

### 400

Invalid partner request or model validation failure.

- `application/json`: `ErrorResponse`

### 404

Not Found

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/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.