SIMWAY
Partners

eSIM profiles

A profile is what you actually sold. This page covers the install payload — which is the part your customer touches — and is honest about how current the usage counters are. Note where these objects come from: an order's esims[] carries the complete profile, so ordinarily you never call the endpoints here to deliver something. They are for reading a profile back afterwards.

The install payload

Every provisioned profile carries an activation object with four routes onto a handset. Give your customer at least two of them: QR codes fail on a phone that is the only screen available, and manual entry fails when someone mistypes a matching id.

FieldWhat it isUse it when
qr_code_data_urlA base64 PNG, ready to put in an <img src>. Scannable at the same size and quiet zone the consumer app uses.The customer has a second screen, or you are printing it into an email or a voucher.
apple_universal_linkA one-tap install link on iOS. A pure transform of the activation code, so it is null exactly when that is.The customer is reading this on the iPhone that will hold the eSIM. It is the highest-conversion route by a distance.
activation_codeThe LPA string: LPA:1$<smdp>$<matching id>. Android can accept it directly on most devices.A copy-and-paste flow, or your own QR rendering.
smdp_addressThe SM-DP+ host and the matching id, as separate fields.The manual entry screen, which is the fallback that always works and the one your support team will walk people through.

Usage counters, and how stale they are

  • data_used_bytes and data_total_bytes are JSON numbers on this API. On the consumer API the same counters are strings. If you have integrated both, they are not the same type.
  • voice_total_min is null on a data-only plan, which is most of the catalogue.

Profile states

StatusMeans
pendingOrdered, not yet issued by the supplier.
provisionedIssued and installable. This is the state a fresh order lands in.
installedThe profile has been downloaded onto a device.
activeIn use, and consuming the bundle.
suspendedHalted.
expiredPast its validity window.
depletedThe bundle is used up.
cancelledVoided.

Addressing a profile

By ICCID, not by an internal id — because the ICCID is what your own support process already has: it is printed on the customer’s screen and it is what they will quote at you. Scope is your account and the mode of the key you send, so a live key cannot read a sandbox profile.

Sandbox profiles are recognisable on sight
ICCID       89999...          19 digits, Luhn-valid, ITU-reserved private-network range
SM-DP+      sandbox.simway.pro   a host we own that can issue nothing
Matching id SB-...               the tell in a support ticket

A sandbox activation code pasted into a real handset fails at DNS rather than reaching somebody else’s SM-DP+. More on the sandbox.

Endpoints

GET/esims

List profiles

Requires a keyRate class read

Newest first, scoped to your account and this key’s mode.

Query parameters

NameTypeRules
statusenumFilter by profile state.One of: pending, provisioned, installed, active, suspended, expired, depleted, cancelled
order_idstringMust begin po_, else a 400 naming order_id.
created_afterISO 8601EXCLUSIVE — >.
limitintegerPage size.1–200Default 50
cursorstringOpaque. Pass back next_cursor from the previous page, or omit it to start again. A malformed cursor is a 400 naming cursor, never a silent first page.≤ 512 characters

Example

Request
curl 'https://api.simway.pro/partner/v1/esims?status=active' \
  -H 'Authorization: Bearer simway_sk_test_ExampleKeyDoNotUse0000000000000000000000000'
200 — One page
{
  "data": [
    {
      "object": "esim",
      "iccid": "8944500102030405062",
      "order_id": "po_c7m2k9x4v1b6n3q8w5t0r2j7",
      "plan_id": "pl_c3n8k5x2v9b4m7q1w6t3r0j5",
      "status": "active",
      "activation": {
        "smdp_address": "rsp.example.com",
        "matching_id": "K2-1A9QX-88ZLM",
        "activation_code": "LPA:1$rsp.example.com$K2-1A9QX-88ZLM",
        "qr_code_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
        "apple_universal_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA%3A1%24rsp.example.com%24K2-1A9QX-88ZLM"
      },
      "usage": {
        "data_used_bytes": 128974848,
        "data_total_bytes": 5368709120,
        "voice_used_min": 0,
        "voice_total_min": null
      },
      "activated_at": "2026-08-18T06:41:03Z",
      "expires_at": "2026-09-17T06:41:03Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors it can return

GET/esims/{iccid}

Get one profile

Requires a keyRate class read

Addressed by ICCID rather than by an internal id, because the ICCID is what your own support process already has: it is on your customer’s screen.

The install payload is complete — an SM-DP+ address and matching id for manual entry, a full LPA: activation code, a scannable QR as a data URL, and an Apple universal link that installs the profile in one tap on iOS.

Path parameters

NameTypeRules
iccid *stringThe ICCID exactly as it was issued.

Example

Request
curl 'https://api.simway.pro/partner/v1/esims/8944500102030405062' \
  -H 'Authorization: Bearer simway_sk_test_ExampleKeyDoNotUse0000000000000000000000000'
200 — A provisioned profile
{
  "object": "esim",
  "iccid": "8944500102030405062",
  "order_id": "po_c7m2k9x4v1b6n3q8w5t0r2j7",
  "plan_id": "pl_c3n8k5x2v9b4m7q1w6t3r0j5",
  "status": "provisioned",
  "activation": {
    "smdp_address": "rsp.example.com",
    "matching_id": "K2-1A9QX-88ZLM",
    "activation_code": "LPA:1$rsp.example.com$K2-1A9QX-88ZLM",
    "qr_code_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
    "apple_universal_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA%3A1%24rsp.example.com%24K2-1A9QX-88ZLM"
  },
  "usage": {
    "data_used_bytes": 0,
    "data_total_bytes": 5368709120,
    "voice_used_min": 0,
    "voice_total_min": null
  },
  "activated_at": null,
  "expires_at": "2026-09-17T06:41:03Z"
}

Errors it can return