Quickstart

Provision a working eSIM end to end. Five minutes, no account, no sales call.

Every step is shown two ways: the CLI command, and the HTTP call it makes. Switch with the tabs, and pick your language once. The choice follows you through the rest of the portal.

0. Get set up

npx firsty init

Claims a sandbox credential and verifies it. Install it once with npm i -g firsty so the rest of the steps run as firsty ..., or keep prefixing them with npx.

For raw HTTP, export a token first: export FIRSTY_TOKEN="$(firsty auth token)", or do the exchange yourself.

1. Pick a plan

firsty catalog packages

Note the planReference of the plan you want.

2. Order the eSIM

firsty esim order

{
  "data": {
    "profileReference": "1234567890123456",
    "externalProfileId": "my-customer-123",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "activationCode": "LPA:1$provider.example.com$ACTIVATION_CODE_HERE",
    "pin1": "1234",
    "puk1": "12345678",
    "pin2": "5678",
    "puk2": "87654321",
    "esimVariant": "travel",
    "status": "released",
    "lifecycleStatus": "preactive",
    "msisdns": [
      {
        "msisdn": "32123456789",
        "primary": true
      }
    ],
    "createdAt": "2026-01-15T09:30:00Z",
    "portIn": {
      "portInRequestReference": "K7Q2M9XA",
      "status": "requested"
    }
  }
}

The body is optional. Send externalProfileId to tag the eSIM with your own customer id, or esimVariant to draw from a specific pool; omit both and you get your account's default variant. On the CLI those are --external-id and --variant.

The response above carries the references you'll use everywhere else, and the LPA activation code for the device. Keep both references: the CLI remembers the eSIM you just ordered and targets it by default, but over raw HTTP you pass them in the path every time.

Note the two state fields. status is the profile on the device, and lifecycleStatus is the line on the network. They move independently, which is the single most common source of confusion here (eSIM lifecycle).

3. Put data on it

An eSIM without a package has no allowance. Attach the plan from step 1:

firsty package order C123456XYZDUSR

4. Hand it to the user

Render the activationCode as a QR code, or deep-link straight into the device's eSIM installer on iOS and Android. Installation and network attach happen on the device, and you see them as status changes (eSIM lifecycle).

5. Watch consumption

firsty esim usage

{
  "data": {
    "profileReference": "string",
    "esimReference": "123456000000000001",
    "iccid": "string",
    "packages": [
      {
        "packageReference": "C123456XYZDUSR_A1B2C3D4",
        "externalTransactionId": "order-12345",
        "type": "data",
        "usage": {
          "total": 5000,
          "used": 1234.5,
          "remaining": 3765.5,
          "unit": "MB"
        }
      }
    ],
    "totals": {}
  }
}

Rather than polling, subscribe to webhooks and react to esim.enabled and package.usage.threshold.