Menu

Expand
Rate this page:

How to use Super SIM eSIM Profiles

To avoid ambiguity, throughout this page Sim (initial cap) refers to the Sim API resource. SIM (all caps) refers to the physical Subscriber Identity Module (that is, a SIM card) associated with a Sim resource.

An ESimProfile resource represents a digital Super SIM profile that can be downloaded onto an eSIM (eUICC) that uses consumer profiles.

There are two different types of eSIMs: consumer and M2M. You can learn more about both solutions in this eSIM whitepaper from the GSMA.

Ask your device manufacturer to confirm what type of profile is supported by your hardware — they are not interchangeable. If you are using an eSIM inside a traditional consumer device, such as a smartphone or a tablet, it likely uses consumer profiles.

The ESimProfile API allows you to request a Super SIM profile for a specific eUICC SIM and to manage your existing eSIM profiles. You create and access ESimProfiles through these endpoints:

https://supersim.twilio.com/v1/ESimProfiles
https://supserim.twilio.com/v1/ESimProfiles/{sid}

When you create an ESimProfile resource, we will attempt to reserve a SIM profile for you on Twilio’s eSIM subscription management service (SM-DP+). This reservation takes place asynchronously. After the reservation completes, you’ll be able to download the SIM profile to your eSIM. You can configure a callback URL to be automatically notified when the SIM profile is available for download and when it has been downloaded.

To use your SIM profile to connect to cellular networks, configure and activate the Sim resource that is created during the reservation process. The Sim resource can be configured before or after the SIM profile is downloaded.

Once a consumer SIM profile has been downloaded to your eSIM, you will no longer be able to make updates to the ESimProfile resource that represents it. You manage the SIM profile’s connectivity using the Sim resource created during the reservation process and you, or an application running on your device, will manage which SIM profile should be enabled from your device.

Supported download methods

There are multiple approaches defined by the GSMA that can be used to download a consumer SIM profile to your device. Twilio currently supports one method: Default SM-DP+. Twilio will support more download methods in the future: for example, downloads based on activation codes and/or QR codes.

Default SM-DP+ generally requires your backend to be able to interact with the LPA or to have direct access to the LPA on the device. You will need to supply the SM-DP+ information to the LPA and then trigger the LPA to download the SIM profile. You may need to consult your eSIM manufacturer or LPA provider to learn how to configure this.

Connecting with your SIM profile

To use your SIM profile to connect to cellular networks, configure and activate the Sim resource that is created when the SIM profile is reserved for you. When your reservation is complete, the ESimProfile resource’s Status will be updated to available and its SimSid will be updated with the unique identifier of the Sim resource you will use to manage its connectivity. This Sim resource can be activated before or after the SIM profile has been downloaded to your eSIM.

If you configured the ESimProfile resource’s CallbackUrl, a notification will be sent to you with the Sim resource’s Sid when the ESimProfile resource’s Status is updated to available. See Asynchrounous updates for more details about the notifications sent.

eSimProfile resource properties

Property Description
Sid The unique string that identifies this resource.
iccid The ICCID associated with the Sim resource.
SimSid The unique string that identifies the Sim resource used to manage this SIM profile’s connectivity.
Status Indicates the status of this resource.
EId Identifier of the eSIM that can download or has downloaded the SIM profile that this resource represents.
SmdpPlusAddress Address of the SM-DP+ from which the SIM profile can be downloaded.
CallbackURL Callback URL for ESimProfile status changes.
CallbackMethod The HTTP method we should use to call CallbackUrl. Can be: GET or POST. The default is POST.

eSimProfile status values

Status Value Description
reserving The initial value of an ESimProfile resource. Your request to create an eSIM profile has been accepted and we are in the process of reserving a SIM profile for you.
available An eSIM profile is ready to be downloaded. A Sim resource has been created. Your account has been charged for the profile.
downloaded The eSIM profile has been claimed. It is not guaranteed that an eSIM profile resource will be updated from available to downloaded after the profile has been downloaded. The ESimProfile resource can no longer be updated.
installed

The eSIM has confirmed that the SIM profile has been successfully installed.

When eSIMs are manufactured with profiles pre-installed, the ESimProfile resource will be added in this state.

failed Your SIM profile either failed to be reserved or can no longer be downloaded from the SM-DP+.

Asynchronous updates

Reserving and downloading a SIM profile completes asynchronously. Throughout this process, the ESimProfile resource will be updated. To receive a notification each time the ESimProfile resource updates, set its CallbackUrl and CallbackMethod properties.

The ESimProfile resource will be updated at each of the following events:

SIM profile successfully reserved

Your SIM profile has been reserved and is ready for download. The Status property will be updated to available. The SmdpPlusAddress property will be updated with the URL of the SM-DP+.

The Sim resource that needs to be activated before you can connect to the cellular networks has also been created. The SimSid property will be updated.

SIM profile reservation failed

Your SIM profile could not be reserved. The Status property will be updated to failed. The ErrorCode and ErrorMessage properties will be updated to indicate what went wrong.

SIM profile downloaded

Your SIM profile has been successfully downloaded. The Status property will be updated to downloaded. The EId property will be updated with the EID of the eSIM that downloaded the SIM profile.

SIM profile failed to download

Something went wrong and your SIM profile can no longer be downloaded. The Status property will be updated to failed. The ErrorCode and ErrorMessage properties will be updated to indicate what went wrong.

SIM profile installed

Your SIM profile has been successfully installed on the eSIM. The Status property will be updated to installed.

Callback values

If you set the CallbackUrl and CallbackMethod properties on your ESimProfile resource, the asynchronous request made to that URL will contain the following parameters:

Callback Value Description
ESimProfileSid The unique SID of the ESimProfile resource that this callback is in reference to.
SimSid The unique SID of the Sim resource used to manage this SIM profile’s connectivity.
SimIccid The ICCID of the SIM profile to be downloaded to your eSIM.
ESimProfileStatus The status of the ESimProfile resource that this callback is in reference to.
EId The EID of the eSIM that can or did download the SIM profile.
SmdpPlusAddress Address of the SM-DP+ from which the SIM profile can be downloaded.
ErrorCode Error code to identify what went wrong.
ErrorMessage Description of what went wrong.

Order an eSIM profile

To request and reserve an eSIM profile for your consumer eSIM, make a POST request to https://supersim.twilio.com/v1/ESimProfiles. Specify the EID of your eSIM in your request.

Property Description
EId Identifier of the eUICC SIM that needs a Super SIM profile.
CallbackUrl The URL we should call using the CallbackMethod after an asynchronous update has finished.
CallbackMethod The HTTP method we should use to call CallbackUrl. Can be: GET or POST. The default is POST.

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 Community Forums or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

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