Overview
Public API (/v1)
Shared rules of the /v1 API: base URL, response envelope, pagination and response language.
Base URL#
Send every request over HTTPS to the address below. A Public API key is required (Authentication), and every response is JSON.
https://api.esimoa.com/v1Endpoints#
| Endpoint | Description |
|---|---|
| GET /v1/esims | Search eSIMs |
| GET /v1/esims/:id | Get an eSIM |
| GET /v1/countries | List countries |
| GET /v1/openapi.json | OpenAPI 3.1 spec (no key needed) |
Response envelope#
Successful responses always include "success": true. Lists come in items and a single result in item.
// List endpoints
{ "success": true, "items": [ ... ], "total": 42, "limit": 10, "offset": 0, "sort": "price" }
// Detail endpoint
{ "success": true, "item": { ... } }For error responses and status codes, see Rate limits & errors.
Pagination#
Lists are paged with limit (1–50, default 10) and offset. offset is always rounded down to a multiple of limit — for example limit=10, offset=15 is treated as offset=10. The offset in the response is the value actually used, and total is the full count.
Tip
Response language#
The lang parameter (ko | en | ja | zh-CN | zh-TW, default en) sets the language of country names, item titles and the purchase page that url points to. Match it to your user’s language.
Prices & caching#
Prices (priceKrw) are esimoa’s selling price as integer KRW. Prices change often — cache search results for a few minutes at most; the esimoa checkout is always the source of truth for the amount charged.