Skip to Content
OpenRoam Docs
eSIMs

Search eSIM plans

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

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.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Query Parameters

countryCode?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?string

Keep local, regional or global destinations.

Value in"local""regional""global"
region?string

Keep the destinations of this region, in display or slug form, for example North America or north-america.

validityDays?integer

Keep the plans valid for exactly this many days; at least 1.

Formatint32
isUnlimited?boolean

Keep the unlimited (true) or the limited (false) plans.

iccid?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?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?integer

Page number, from 1; default 1.

Formatint32
limit?integer

Page size, 1 to 100; default 10.

Formatint32

Response Body

OK

  1. response

A page of destinations; pagination.totalCount counts destinations that have an orderable offer.

items*array<>
pagination*

Paging of a list response.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/esims/search?countryCode=FR&category=regional&region=Europe&validityDays=7&isUnlimited=false&currency=USD&page=1&limit=10'
Example Response
{  "items": [    {      "id": "destn_k3m7q2t5w4y6b2d4f6h3j5n7pq",      "name": "Europe",      "countryCode": null,      "category": "regional",      "logoUrl": "https://cdn.openroam.test/esims/europe.png",      "description": null,      "offers": [        {          "publicId": "esim_eu_3gb_7d",          "name": "Europe 3 GB 7 days",          "description": null,          "price": {            "amount": 25,            "currency": "USD"          },          "requiredInputs": [            {              "name": "isInstant",              "type": "boolean",              "required": false,              "description": "Defaults to true, which creates the eSIM when the order is fulfilled. False delivers an entitlement, and the eSIM is created later through provisioning."            }          ],          "details": {            "validityDays": 7,            "data": {              "amount": 3072,              "unit": "MB",              "isUnlimited": false,              "label": "3 GB"            },            "voice": null,            "sms": null,            "apn": {              "apn": "internet",              "apnUsername": null,              "apnPassword": null            },            "properties": {              "withKyc": false,              "withTopUp": true,              "withHotspot": true,              "withDataRoaming": true,              "withSubscription": false,              "withDestinationInstall": false,              "withUsageCheck": true,              "technology": "eSIM",              "activation": "first-use",              "charge": "one-time"            },            "restrictions": {              "throttle": false,              "throttleSpeed": null,              "throttleUnit": null,              "throttleThreshold": null,              "throttleThresholdUnit": null,              "expireInDays": 30            },            "notes": [              "Data only. Calls and SMS are not included."            ],            "plan": null          }        }      ],      "details": {        "destinationCode": "EU",        "region": "Europe",        "coverage": [          {            "countryCode": "DE",            "name": "Germany",            "networks": [              "4G"            ],            "carriers": [              "Telekom"            ]          },          {            "countryCode": "FR",            "name": "France",            "networks": [              "4G",              "5G"            ],            "carriers": [              "Orange"            ]          },          {            "countryCode": "IT",            "name": "Italy",            "networks": [              "4G"            ],            "carriers": [              "TIM"            ]          }        ]      }    }  ],  "pagination": {    "currentCount": 1,    "totalCount": 1,    "skip": 0,    "limit": 10,    "hasMore": false,    "page": 1,    "totalPages": 1  }}