Menu

Expand
Rate this page:

ESimProfile Resource

We are currently piloting the release of Super SIM on eSIM. Interested in trying it out? Reach out to us here, or sign up for the pilot right away!

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

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

An ESimProfile instance can be referenced in the API by its unique sid:

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

An ESimProfile allows you to request a Super SIM profile for an eUICC SIM and allows you to manage the eSIM profiles.

When you create an ESimProfile resource, a SIM profile will be asynchronously reserved for you on Twilio’s eSIM subscription management service (SM-DP+). 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 update the ESimProfile resource that represents it. You will 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.

Please make sure you have the following two items before using this API to reserve a Super SIM Profile:

Reserving a SIM profile will result in the corresponding SIM resource being associated with your account and your account being charged for the cost of a SIM profile.

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

EsimProfile properties

Resource Properties in REST API format
sid
sid<HP> Not PII

The unique string that we created to identify the eSIM Profile resource.

account_sid
sid<AC> Not PII

The SID of the Account to which the eSIM Profile resource belongs.

iccid

The ICCID associated with the Sim resource.

sim_sid
sid<HS> Not PII

The SID of the Sim resource that this eSIM Profile controls.

status
enum:status Not PII

The status of the eSIM Profile. Can be: reserving, available, downloaded, installed or failed. See the eSIM Profile Status Values for a description of each.

eid
string Not PII

Identifier of the eUICC that can claim the eSIM Profile.

smdp_plus_address
url Not PII

Address of the SM-DP+ server from which the Profile will be downloaded. The URL will appear once the eSIM Profile reaches the status available.

error_code
string Not PII

Code indicating the failure if the download of the SIM Profile failed and the eSIM Profile is in failed state.

error_message
string Not PII

Error message describing the failure if the download of the SIM Profile failed and the eSIM Profile is in failed state.

date_created
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

url
url Not PII

The absolute URL of the eSIM Profile resource.

Status values

The table below describes the available status values of an ESimProfile instance.

reserving The initial value of an ESimProfile. 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 ESimProfile resource will be updated from available to downloaded after the profile has been downloaded. The ESimProfile 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+.

Create an ESimProfile resource to reserve a Super SIM profile

post
https://supersim.twilio.com/v1/ESimProfiles
Parameters
Parameters in REST API format
eid
Required
post string Not PII

Identifier of the eUICC that will claim the eSIM Profile.

callback_url
Optional
post string Not PII

The URL we should call using the callback_method when the status of the eSIM Profile changes. At this stage of the eSIM Profile pilot, the a request to the URL will only be called when the ESimProfile resource changes from reserving to available.

callback_method
Optional
post http_method Not PII

The HTTP method we should use to call callback_url. Can be: GET or POST and the default is POST.

Example 1
        
        
        

        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 callback_url and callback_method 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 smdp_plus_address 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 sim_sid property will be updated.

        SIM profile reservation failed

        Your requested SIM profile could not be reserved. The status property will be updated to failed. The error_code and error_message 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 error_code and error_message 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 callback_url and callback_method properties on your ESimProfile resource, the asynchronous request made to that URL will contain the following parameters:

        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.
        Example 2
              
              
              
              Example 3
                    
                    
                    

                    As mentioned before, we are currently piloting the release of Super SIM on eSIM. Interested in trying it out? Reach out to us here, or sign up right away!

                    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. How could this documentation serve you better?

                          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