> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onroamly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Programmatic access to Roamly's travel eSIM plan catalog.

The Roamly API is built for two kinds of partner.

**Listing partners** — comparison sites, directories and publishers who show
Roamly plans alongside other providers. The catalog endpoints give you every
destination and plan we sell, with live pricing, so your listings stay current
without anyone maintaining a spreadsheet.

**Enterprise customers** — businesses buying eSIMs for their own travellers,
staff or customers. Alongside the catalog, you can retrieve the eSIMs on your
account: installation details, activation status and data usage, ready to drop
into your own dashboard or travel tooling. If you need purchasing wired into
your systems as well, [talk to us](mailto:hello@onroamly.com) — we build
bespoke integrations for volume customers.

```text theme={null}
https://api.onroamly.com
```

All endpoints are `GET` requests returning JSON, authenticated with an API key —
see [Authentication](/authentication).

## Endpoints

| Endpoint                                                                | What it returns                                                       |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`GET /v1/destinations`](/api-reference/destinations/list-destinations) | Every country and regional bundle, with plan counts and lowest prices |
| [`GET /v1/plans`](/api-reference/plans/list-plans)                      | The full sellable catalog, filterable by destination                  |
| [`GET /v1/plans/{planId}`](/api-reference/plans/get-a-plan)             | A single plan                                                         |
| [`GET /v1/esims`](/api-reference/esims/list-your-esims)                 | eSIMs purchased by your account                                       |
| [`GET /v1/esims/{esimId}`](/api-reference/esims/get-an-esim)            | A single eSIM, with usage                                             |

## Quick example

```bash theme={null}
curl "https://api.onroamly.com/v1/plans?destination=jp&currency=USD" \
  -H "Authorization: Bearer rk_live_…"
```

```json theme={null}
{
  "data": [
    {
      "id": "4f6b2c1e-8a3d-4e2f-9c5b-1a2b3c4d5e6f",
      "name": "Japan 5GB 30 days",
      "destination": { "slug": "jp", "name": "Japan", "type": "country", "flagEmoji": "🇯🇵" },
      "dataAmountGB": 5,
      "dataType": "total",
      "validityDays": 30,
      "speed": "4G/5G",
      "canTopUp": true,
      "coverage": ["JP"],
      "price": { "amount": 9.35, "currency": "USD" },
      "url": "https://www.onroamly.com/explore/jp/4f6b2c1e-8a3d-4e2f-9c5b-1a2b3c4d5e6f"
    }
  ],
  "meta": { "count": 1, "currency": "USD" }
}
```

## Good to know

* **Currencies** — prices are in `AUD` by default. Pass `?currency=USD` for
  US-dollar prices, converted at a fixed reference rate; checkout on
  onroamly.com always charges AUD.
* **Freshness** — the catalog is served from a short-lived cache and reflects
  changes within about a minute. Polling more than a few times an hour is
  rarely useful.
* **Your eSIMs** — an API key belongs to one Roamly account, and the
  `/v1/esims` endpoints only ever return that account's eSIMs. Usage figures
  come from an hourly poll, so `usage.updatedAt` tells you how fresh a reading
  is.
* **Purchasing** — buying through the API isn't public yet. Each plan's `url`
  links to its purchase page on onroamly.com, and for volume customers we set
  up purchasing directly — [get in touch](mailto:hello@onroamly.com).