eSimerge

eSIMs

Inspect provisioned eSIMs and monitor live usage.

GET /v1/esims/{id}

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. On unlimited-data plans the usage counters stay at 0/null for the eSIM's whole lifetime — status is the reliable signal that the eSIM has connected and is in use (see the note under the usage endpoint below).

Two different dates — install_by vs expires_at

install_by is the deadline for installing the profile (typically 30 days from purchase). It has nothing to do with how long the package runs. expires_at is the end of the plan's validity and is null until the eSIM activates; from activation onwards it carries the real expiry, so a 1-day package expires one day after first use. validity_days always states the package length. expires_at stays populated after activation even if the profile goes inactive, and expired turns true once that date passes.

A few destinations cannot be tracked upstream. For those, tracking_supported is false, tracking_unsupported_reason is 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",
  "install_by": "2026-06-25T12:00:00Z",
  "validity_days": 30,
  "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.

GET /v1/esims/{id}/usage

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.

Unlimited plans — use status, not the counters

On unlimited-data packages, data_used_mb, data_allowed_mb and data_remaining_mb stay 0 or null for the whole lifetime of the eSIM — the counters never move, so they cannot tell you whether the eSIM is connected. To detect "connected / in use", read the top-level status field instead: it is resolved from the eSIM's lifecycle event feed (new → downloaded → installed → activated) and reflects real provider events. Treat status of installed or earlier as "not yet started"; once it flips to activated, the eSIM has attached to a network and is in use. This works the same way as the allowance counters do on capped/limited packages, so you can drive your "not yet started" state off status uniformly across both plan types.

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",
  "install_by": "2026-06-25T12:00:00Z",
  "expired": false
}