Menu

Expand
Rate this page:

How to Use Super SIM eSIM Profiles

Many Internet of Things manufacturers wish to incorporate eSIMs (eUICC SIMs) into their products rather than traditional SIMs in order to take advantage of eSIMs’ remote SIM provisioning capabilities. The good news is that they can do so with Super SIM and continue to take full advantage of Super SIM’s global connectivity via multiple tier-1 networks.

In fact, working with a virtual Super SIM installed in an eSIM is no different from working with a physical one in card or chip form: you use the same API calls to assign it to a Fleet and manage its state. However, you need to follow a slightly different process to obtain the virtual SIM — called an eSIM profile — and to prepare for its installation on a device.

The Super SIM API provides tools for you to create, or ‘reserve’, Super SIM eSIM profiles, which are accessible as eSimProfile resources. To make use of the eSIM profiles you have created, you need eUICC (Embedded Universal Integrated Circuit Card) hardware to store them on your IoT device, and Local Profile Assistant (LPA) software, also on the device, to download profiles and manage those installed in the eUICC.

This guide will introduce you to the Super SIM API used to reserve and manage Super SIM eSIM profiles, and show you the methods you can apply to install profiles onto devices. If you’re new to eSIMs, you may prefer to start with the guide Get Started with Super SIM eSIM Profiles for eUICCs and then return to this longer, more detailed document.

How are eSIM profiles installed?

To use eSIMs, an IoT device needs LPA software. The LPA downloads eSIM profiles from an SM-DP+ (Subscription Manager Data Preparation) server, installs them in the device’s eUICC, and manages switching between profiles — the digital equivalent of swapping SIM cards. The LPA may also provide an interface through which users swap the current profile for another to switch between cellular connectivity providers, if that’s a choice you as a device manufacturer have chosen to grant them.

There are many ways to implement an LPA. It may be part of a mobile device operating system. For example, many Android devices are already eSIM compatible, and the OS supports the installation of third-party LPAs in addition to its own. If you are building your own IoT hardware, you will need to discuss with your cellular module supplier how to develop and install a suitable LPA. If your choice of eUICC already incorporates an LPA, you will still need to code your application to communicate with it.

The process of installing an eSIM profile goes like this:

  1. You create an eSIM profile on a SM-DP+ server. This is done using the Super SIM API, and is typically referred to as “reserving” a profile.
  2. You provide the device’s LPA with the address of the SM-DP+ server. There are several methods, discussed shortly, that you can choose from.
  3. The LPA contacts the SM-DP+ server and receives the reserved eSIM profile, which it installs in the device’s eUICC.

The SM-DP+ server is an online resource that makes eSIM profiles available for download. Think of it as a virtual warehouse full of ready-to-use digital SIMs.

Profile installation methods

There are various ways of providing the LPA with the address of the SM-DP+ it should contact. Super SIM supports the following methods:

SM-DP+ Default binds the reserved profile to a specific eSIM which is identified by its eSIM ID (EID). Only that eSIM can then make use of the reserved profile. The LPA sends the host’s EID to the server, which responds with the eSIM profile reserved for that EID. When you reserve eSIM profiles with this method in mind, you need to know the identity of the target device.

Here is a typical call flow for downloading Super SIM profiles using the SM-DP+ Default method:

A typical call flow for downloading Super SIM profiles using SM-DP+ Default

However the LPA gets the address of an SM-DP+ server, when it contacts the server it will receive a profile and install it in the eUICC. Once the eSIM profile has been installed and activated, the host device is able to connect to the Internet.

Let’s go through each of these phases in detail.

Prepare an eSIM profile

1. Reserve an eSIM profile

To reserve a profile, you need to send an HTTP POST request containing data appropriate to your chosen installation method to:

https://supersim.twilio.com/v1/ESimProfiles

This will create a new eSimProfile resource and initiate the process of reserving its linked eSIM profile on the SM-DP+ server.

If you wish to use the Default SM-DP+ method of profile installation, provide the target device’s EID as a URL-encoded request parameter. For example, to make the request using curl:

curl -X POST https://supersim.twilio.com/v1/ESimProfiles \
  -d Eid=<DEVICE_EID> \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Or to do using the Twilio CLI:

twilio api:supersim:v1:esim-profiles:create \
  --eid=<DEVICE_EID>

In every case, the response will include the URL of the eSimProfile resource you will work with.

Asynchronicity

Reserving an eSIM profile is an asynchronous operation, so the new profile will not be ready to use immediately, though the eSimProfile resource is available straight away. If you’re testing the process at the desktop, you can poll the URL provided in the response to your initial request and view the status field of the poll response. When the status is available, the profile is ready for use.

A better approach for server-side code is to provide a callback URL with your initial request.

twilio api:supersim:v1:esim-profiles:create \
  --eid=<DEVICE_EID> \
  --callback-url=<YOUR_CALLBACK_ENDPOINT>

Twilio will issue a GET request to this URL when the eSIM profile is available for download, but you can change this ti POST:

twilio api:supersim:v1:esim-profiles:create \
  --eid=<DEVICE_EID> \
  --callback-url=<YOUR_CALLBACK_ENDPOINT> \
  --callback-method=post

2. Assign the profile’s Sim to a Fleet and activate it

Part of the creation of an eSIM profile is the generation of an associated Sim resource which you use to manage the profile’s SIM data. The resource’s SID will be included in the poll response as the value of the sim_sid field once the eSimProfile resource’s status has become available. At this point, you can also read the SM-DP+ address from the resource’s smdp_plus_address field.

Use the extracted Sim resource SID assign it to a Fleet resource and to activate it:

curl -X POST https://supersim.twilio.com/v1/Sims/<YOUR_SIM_SID> \
  -d "Fleet=<YOUR_FLEET_SID>" \
  -d "Status=active" \
  -u "<YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>"
twilio api:supersim:v1:sims:update \
  --sid=<YOUR_SIM_SID> \
  --fleet=<YOUR_FLEET_SID> \
  —-status=active

Assignment and activation are shown here as a single call, but you may choose to perform these tasks separately and at different points in time, depending on your workflow and use case.

3. Pass the SM-DP+ address to the LPA

This stage will depend on your chosen installation method.

Default SM-DP+

You will need to provision the target device with the SM-DP+ address you received earlier. If you are working with an eSIM-compatible Android or iOS device, each OS’ Settings app provides a path to enter this information manually — for more information, please see Get Started with Super SIM eSIM Profiles for eUICCs. For an embedded device, however, you will need to consult your LPA provider to learn how to code your application to provision the LPA with the address after retrieving it from your cloud.

3. Install the eSIM profile

Again, this stage will depend on your chosen download method.

Default SM-DP+

In the case of the Default SM-DP+ method, installation typically takes place when the LPA first starts up and there is no profile in the eUICC: it will contact the provisioned server and pass the host EID. The server will respond with the eSIM profile for installation. If the SM-DP+ server address has just been entered manually — for example, into an Android or iOS device — then the LPA will contact the server at that time.

Take a look at the guide Get Started with Super SIM eSIM Profiles for eUICCs to see how to apply the installation methods to Android and iOS devices.

A Super SIM profile can be downloaded only once to an eSIM. Once it is downloaded, it can be used only with that eSIM. It cannot be downloaded again or used with another eSIM.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more