QR Code & eSIM Installation

After placing an order, you use the orderReference to retrieve installation details for your end user. There are several delivery formats depending on how you want to present the eSIM to the user.

The endpoint

GET /v2.5/esims/assignments?reference={orderReference}

The response format is controlled by the Accept header.

Format options

ZIP of QR code images

The most common format for delivering eSIMs to end users. Returns a ZIP file containing one PNG QR code per eSIM, plus a CSV mapping ICCIDs to their codes.

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

JSON

Returns structured installation data for each eSIM. Useful if you want to generate your own QR code or build a custom installation flow.

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

{
  "iccid": "8944123456789012345",
  "matchingId": "A1B2-C3D4-E5F6-G7H8",
  "smdpAddress": "rsp.example.com",
  "profileStatus": "Released"
}

CSV (default)

If no Accept header is provided, the response is a plain text CSV. Useful for batch processing.

Direct install URLs

For a smoother end-user experience, request direct install URLs using the additionalFields=installUrl query parameter:

curl "https://api.esim-go.com/v2.5/esims/assignments?reference={orderReference}&additionalFields=installUrl" \
  -H 'X-API-Key: $API_KEY' \
  -H 'Accept: application/json'

This adds two fields to the JSON response:

Field	Description
appleInstallUrl	Deep link for direct eSIM installation on iOS 17.4 and above — no QR scan required
androidInstallUrl	Deep link for direct eSIM installation on compatible Android devices

Direct install URLs let users tap a link in your app or email to install the eSIM without needing to open a camera or scanner.

Note

Direct install links require the user’s device to support eSIM and be connected to the internet. The QR code remains the fallback for devices or OS versions that do not support direct install.

Profile status

The profileStatus field indicates the current state of the eSIM profile:

Status	Meaning
Released	Profile created, not yet downloaded to a device
Installed	Successfully downloaded and installed on a device

Attempting to retrieve installation details for a deactivated eSIM returns 410 Gone.