Quickstart

From the partner portal → Developers → API Keys → New key. Pick Sandbox to receive a key in the form esm_sk_test_….

The secret is shown only once — store it somewhere safe.

Each plan has an id prefixed with esm_plan_. Use it when issuing an order.

curl https://portal.esimerge.com/api/public/v1/catalog \
  -H "Authorization: Bearer esm_sk_test_..."

The catalog is paginated. Pass page and per_page (default 1000, max 1000) and follow links.next until it is null to ingest everything (~18 requests for 18,000 plans).

let page = 1, all = [];
while (true) {
  const res = await fetch(`https://portal.esimerge.com/api/public/v1/catalog?page=${page}&per_page=1000`, {
    headers: { Authorization: "Bearer esm_sk_test_..." },
  });
  const body = await res.json();
  all.push(...body.data);
  if (!body.links?.next) break;
  page += 1;
}
console.log(all.length, "plans");

Send plan_id to POST /v1/orders. Use the Idempotency-Key header to avoid duplicate provisioning on retries.

curl -X POST https://portal.esimerge.com/api/public/v1/orders \
  -H "Authorization: Bearer esm_sk_test_..." \
  -H "Idempotency-Key: 8f0b1f9e-1f70-4a3e-9b3a-2c2bdcf7a1d2" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"esm_plan_sa_5gb_30d"}'

Response

{
  "id": "esm_order_AbCdEf...",
  "object": "order",
  "status": "issued",
  "esim": {
    "id": "esm_esim_AbCdEf...",
    "iccid": "8988000000000000000",
    "qr_code": "LPA:1$smdp.esimerge.com$...",
    "smdp_address": "smdp.esimerge.com",
    "activation_code": "..."
  },
  "request_id": "req_..."
}

Convert the qr_code value into a QR image (any QR library on your side) and show it for the user to scan. iOS 12.1+ and most modern Android devices are supported.

Register an endpoint to receive events (esim.activated, esim.expired, esim.usage.threshold). Details on the Webhooks page.