eSIMs

Returns the eSIM record including install material (QR / SM-DP+ / direct install URLs for iOS and Android), lifecycle timestamps, the lifecycle event feed and the network locations the profile attached to.

status is resolved from the latest lifecycle event (new → downloaded → installed → activated → expired), not from the order record, so it reflects the true profile state. expires_at stays populated after activation even if the profile goes inactive, and expired turns true once that date passes.

Calling plans and a few destinations (currently Thailand and Japan) cannot be tracked upstream. For those, tracking_supported is false, tracking_unsupported_reason is calling_plan or destination_not_supported, and status, usage, expires_at, events and locations are null or empty.

curl https://portal.esimerge.com/api/public/v1/esims/esm_esim_AbCdEf \
  -H 'Authorization: Bearer esm_sk_test_...'

Example response

{
  "id": "esm_esim_AbCdEf...",
  "object": "esim",
  "order_id": "esm_order_AbCdEf...",
  "iccid": "8988000000000000000",
  "status": "active",
  "qr_code": "LPA:1$smdp.esimerge.com$ABCDEF",
  "smdp_address": "smdp.esimerge.com",
  "activation_code": "ABCDEF",
  "ios_install_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.esimerge.com$ABCDEF",
  "android_install_url": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.esimerge.com$ABCDEF",
  "installed_at": "2026-05-26T12:10:00Z",
  "activated_at": "2026-05-26T12:11:30Z",
  "expires_at": "2026-06-25T12:11:30Z",
  "expired": false,
  "tracking_supported": true,
  "tracking_unsupported_reason": null,
  "usage": { "data_used_mb": 1830, "data_allowed_mb": 5120, "data_remaining_mb": 3290 },
  "events": [
    { "status": "activated", "iccid": "8988000000000000000", "eid": null, "occurred_at": "2026-05-26T12:11:30Z" },
    { "status": "installed", "iccid": "8988000000000000000", "eid": null, "occurred_at": "2026-05-26T12:10:00Z" },
    { "status": "downloaded", "iccid": "8988000000000000000", "eid": null, "occurred_at": "2026-05-26T12:09:10Z" },
    { "status": "new", "iccid": "8988000000000000000", "eid": null, "occurred_at": "2026-05-26T12:00:00Z" }
  ],
  "locations": [
    { "operator": "Vodafone", "network": "Vodafone UK", "country": "United Kingdom", "country_code": "GB", "mcc": "234", "mnc": "15", "occurred_at": "2026-05-26T12:12:00Z" }
  ],
  "available_networks": ["EE", "O2", "Three", "Vodafone UK"],
  "coverage": [
    { "country_code": "GB", "country_name": "United Kingdom", "networks": ["EE", "O2", "Three", "Vodafone UK"] }
  ],
  "coverage_count": 1,
  "device": {
    "eid": "89049032000000000000000000000123",
    "euicc_manufacturer": "Thales (Gemalto)",
    "device_hint": "Apple iPhone / iPad, Google Pixel",
    "device_model": null,
    "note": "EID identifies the eSIM chip, not the handset. The exact device model is not reported by the provider."
  }
}

available_networks lists every mobile network the plan can attach to, while locations[] shows the network the device is actually connected to; coverage breaks the same networks down per country for regional and global plans.

device is derived from the EID reported in the event feed. An EID identifies the eSIM chip, so we return the eUICC manufacturer and a hint of the devices that usually carry it — device_model is always null because no handset model is reported upstream.

Returns the current usage counters, the remaining balance and a per-day breakdown (date, amount and location) — the daily rows are reported for unlimited plans too, where the allowance counters are not meaningful. When the eSIM cannot be tracked, tracking_supported is false and the counters are null with an empty daily array.

curl https://portal.esimerge.com/api/public/v1/esims/esm_esim_AbCdEf/usage \
  -H 'Authorization: Bearer esm_sk_test_...'

Example response

{
  "object": "usage",
  "esim_id": "esm_esim_AbCdEf...",
  "status": "active",
  "tracking_supported": true,
  "tracking_unsupported_reason": null,
  "data_used_mb": 1830,
  "data_allowed_mb": 5120,
  "data_remaining_mb": 3290,
  "total_used_mb": 1830,
  "daily": [
    { "date": "2026-05-27", "data_used_mb": 806.5, "location": "United Kingdom" },
    { "date": "2026-05-26", "data_used_mb": 1024.5, "location": "United Kingdom" }
  ],
  "expires_at": "2026-06-25T12:11:30Z",
  "expired": false
}