Skip to main content
Everything else in this API ends when money moves. An eSIM ends when a person successfully installs a profile on a handset — which is a step you cannot perform, cannot verify directly, and can very easily make harder than it needs to be.

​
What you are actually handing over

One string. Everything else is a way of getting that string into a phone.
The installation endpoint returns it three ways, and they are the same credential in different clothing:

​
Offer them in this order

  1. Universal link. One tap. Nothing to scan, nothing to type, no second device. Works on iOS 17.4+ and recent Android.
  2. QR code. Universally understood, but needs a second device — see below.
  3. Manual entry. Always works, and nobody enjoys it. It is the fallback, not the default.

​
The QR problem

A phone cannot scan a QR code displayed on its own screen. This catches nearly every integration once. Someone opens your app on the phone that will use the eSIM, sees a QR, and has nothing to scan it with. Handle it explicitly:
  • Lead with the universal link when the customer is on the target device.
  • Say so beside the QR: “Scan this from the device that will use the eSIM.”
  • Make the manual details copyable, because they are what someone falls back to.
  • Offer to email or message the QR, so it can be opened on a laptop and scanned from the phone.
Sending the install details by email is a legitimate flow, not a workaround. A traveller printing a QR before a flight is doing the sensible thing.

​
Treat the code as a credential

Whoever holds the activation code can install the eSIM. There is no second factor, and the profile can only be installed once.
  • Do not log it. Not in request logs, not in error reports, not in analytics.
  • Do not show it to staff. The Sakawave admin API deliberately does not return it, for exactly this reason — a support tool that can hand out activation codes can be talked into handing out activation codes.
  • Show it to the person the eSIM is for, and nobody else.
  • It does not need to be stored by you. Fetch it from /installation when it is needed.

​
Device support

Nothing in this API can tell you whether a particular handset supports eSIM. Broadly: Ask before you sell. The most common support case is not a broken eSIM; it is a phone that was never going to take one, or one still locked to a network. A useful check a customer can run themselves: dial *#06#. If an EID appears alongside the IMEI, the device supports eSIM.

​
Reading the status back

You cannot observe the install directly, but the status tracks it closely enough. An eSIM sitting at ready days after purchase is the signal that someone is stuck. That is the moment to send the install details again, not after they complain. esim.profile.installed fires on the transition, so you can prompt on silence rather than polling for it.