Delivering eSIMs

Once an order completes you have an eSIM to hand to your customer. eSIMify does not contact your customer, so this step is yours.

The order gives you the ICCID of each eSIM. The install details are on the eSIM.

Fetch the eSIM with GET /v1/esims/{iccid}. Everything you need is in three fields:

Field	Use it for
install_links	A one-tap install link, on the phone itself.
qr_code_url	A QR code image, on any other screen.
activation	Manual entry, as the fallback.

Offer the one-tap link or the QR code first, and keep manual entry as the fallback.

What an eSIM is made of

Every eSIM comes with an activation string, often called the LPA string. It is in activation.lpa:

LPA:1$smdp.example.com$ACTIVATION-CODE

It has two parts the phone needs: the SM-DP+ address (the server the phone downloads the eSIM from) and the activation code. The QR code is this same string drawn as a picture.

One-tap install link

On the phone itself, a link is easier than a QR code. install_links gives you one for each platform, ready to use:

{
  "install_links": {
    "ios": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA%3A1%24smdp.example.com%24ACTIVATION-CODE",
    "android": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA%3A1%24smdp.example.com%24ACTIVATION-CODE"
  }
}

Show install_links.ios on an iPhone and install_links.android on an Android phone. Tapping the link opens the phone’s own eSIM setup screen.

The activation string inside each link is percent-encoded. Use the link exactly as returned and do not encode it again.

• iPhone: needs iOS 17.4 or later.
• Android: works on recent phones with Google Play services.

Older phones do not support these links, so always show the QR code or the manual details as well.

QR code

qr_code_url is the address of a PNG image of the QR code. It needs no API key, so you can use it directly:

<img src="QR_CODE_URL_FROM_THE_API" alt="eSIM QR code" width="240" height="240" />

Show the QR code on a screen other than the phone being set up, or in an email the customer can open on a laptop. The customer scans it from the phone’s settings:

• iPhone: Settings, Mobile Service, Add eSIM, Use QR Code.
• Android: Settings, Network and internet, SIMs, Add eSIM. The wording differs between phone makers.

Scanning needs a second screen, so inside a mobile app lead with the one-tap link and keep the QR code for email and desktop.

Anyone who has the address can see the QR code and install the eSIM. Send it only to the customer the eSIM is for. If you would rather not share the address, draw the QR code yourself from activation.lpa.

The address does not expire and cannot be revoked. It stops working, with 404, only if the eSIM is cancelled. It allows 240 requests a minute from one IP address, then answers 429 with Retry-After. Link to it from the customer’s device or keep a copy of the image. Do not fetch it in bulk from one server.

Manual entry

If neither works, the customer can type the details in. Show activation.smdp_address and activation.activation_code as two separate values, with a copy button for each.

More than one eSIM in an order

An order with a quantity above 1 returns one eSIM for each unit. Each traveller needs their own. Fetch each ICCID in the order’s esims list and deliver each one separately. An eSIM can be installed on one phone only.

Count the entries in esims. A partially_completed order holds fewer eSIMs than quantity.

When the install details are missing

In rare cases a live eSIM is issued before its install details are stored. Then qr_code_url, install_links.ios, install_links.android and the three activation fields are null. Fetch the eSIM again a little later. They are also null for a cancelled eSIM.

What to tell your customer

• Install the eSIM before travelling, on Wi-Fi. Installing needs an internet connection.
• Most plans start when the eSIM first connects to a network at the destination, not when it is installed.
• At the destination, switch on the eSIM line and turn on data roaming for it.
• Do not delete the eSIM while the plan is active. Most eSIMs can be installed only once.
• The phone must be carrier-unlocked and support eSIM.

After delivery

• Keep the ICCID with the booking, so your support team can find the eSIM later.
• Let the customer open the install details again from your app or their confirmation email.
• Listen for esim.activated to know the customer is connected, and for esim.usage_80 to offer a top-up. After a top-up the usage events can be sent again for the new allowance. In live these events arrive with a delay, and some networks send no usage at all. See eSIM events in live.