Skip to content
eSIM Go Developer Docs

Quick Start

This guide walks you through the essential steps to go from a new account to a delivered eSIM QR code, using the API directly.

Before you start

You’ll need an eSIM Go account with a positive balance. If you haven’t set one up yet, follow the Account Setup guide first.

Once your account is ready, generate your API key from Account Settings → API Details in the portal. You’ll need it for every request.

Step 1: Browse the catalogue

Find a bundle to order by browsing the catalogue. This returns all bundles available to your organisation.

Terminal window
curl https://api.esim-go.com/v2.5/catalogue \
  -H 'X-API-Key: $API_KEY'

Pick a bundle name from the response — for example esim_1GB_7D_NL_V2. Bundle names are case sensitive.

Step 2: Validate your order

Before spending credit, use type: validate to confirm the order would succeed. A validate request runs all the same checks as a real order but does not charge your balance.

Terminal window
curl -X POST https://api.esim-go.com/v2.5/orders \
  -H 'X-API-Key: $API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "validate",
    "quantity": 1,
    "item": "esim_1GB_7D_NL_V2"
  }'

A successful validate response includes a total value. If validation fails, the response explains why.

Step 3: Place the order

Switch type to transaction to place a real order. Setting assign: true automatically assigns the bundle to a new eSIM. Leave iccid empty to have a new eSIM created.

Terminal window
curl -X POST https://api.esim-go.com/v2.5/orders \
  -H 'X-API-Key: $API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "transaction",
    "quantity": 1,
    "item": "esim_1GB_7D_NL_V2",
    "assign": true,
    "iccid": ""
  }'

A successful response includes statusMessage: "Order completed" and an orderReference. Save the orderReference — you need it to download QR codes.

Step 4: Download QR codes

Use the orderReference from step 3 to download a ZIP of QR code images. Each eSIM in the order gets its own QR code PNG.

Terminal window
curl "https://api.esim-go.com/v2.5/esims/assignments?orderReference={orderReference}" \
  -H 'X-API-Key: $API_KEY' \
  -H 'Accept: application/zip' \
  --output qr_codes.zip

The ZIP also contains a CSV with the ICCID for each eSIM.

What’s next

  • Give the QR code to your end user — they scan it to install the eSIM on their device
  • Track bundle status with GET /v2.5/esims/{iccid}/bundles/{name}
  • Set up webhooks to receive real-time usage and status notifications
  • Read the full API reference for all available endpoints