ESimProfile Resource

Each Super SIM eSIM profile costs $3. Your Twilio account will be charged before the eSIM profile becomes available for download.

Volume discounts are available. Contact sales-wireless@twilio.com to speak to an IoT Sales Specialist.

There are multiple approaches defined by the GSMA that can be used to download a consumer SIM profile to your device.

The Default SM-DP+ method uses the EID of the eSIM to reserve an eSIM profile on the SM-DP+ server. Using your Local Profiles Assistant (LPA), your device can reach out to the SM-DP+ URL provided to it to check if there is a profile available for it. This method can be advantageous if you have a large number of devices for which you already know the EIDs. You can instruct all of your devices to contact the same SM-DP+ URL and not worry about giving each device a unique matching ID to identify the eSIM profile for it. To use this approach, provide the EID of your eSIM as the eid property when reserving an eSIM profile through this resource. If your LPA or device prompts you for a matching ID or an activation code, leave it blank or provide an empty string.

The Activation Code method can be used to reserve an eSIM profile that can be claimed and downloaded by any eSIM enabled device. You do not need to know the EID of the eSIM that will claim the eSIM profile. Instead, when you create an eSIM Profile resource, an eSIM profile will be reserved on our SM-DP+ server and a matching ID will be generated, identifying that specific profile. Any eSIM capable device can then contact the SM-DP+ server at its address and provide the eSIM profile's matching ID to claim it. This is the approach typically used when QR codes are used to add eSIM profiles to devices. To use the Activation Code approach, when creating an eSIM Profile resource, set the generate_matching_id request parameter to true.

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

The ESimProfile resource will typically move through new and reserving within a few seconds and does not require you to take any action.

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:

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.

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.

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.

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.

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

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:

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function fetchEsimProfile() {
11
  const esimProfile = await client.supersim.v1.esimProfiles("Sid").fetch();
12

13
  console.log(esimProfile.sid);
14
}
15

16
fetchEsimProfile();

1
{
2
  "sid": "Sid",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "iccid": "8988307aaaaaaaaaaaaa",
5
  "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
  "status": "available",
7
  "eid": "89049032005008882600033489aaaaaa",
8
  "smdp_plus_address": "sm-dp-plus.twilio.com",
9
  "matching_id": null,
10
  "activation_code": null,
11
  "error_code": null,
12
  "error_message": null,
13
  "date_created": "2020-09-01T20:00:00Z",
14
  "date_updated": "2020-09-01T20:00:00Z",
15
  "url": "https://supersim.twilio.com/v1/ESimProfiles/HPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
16
}

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function listEsimProfile() {
11
  const esimProfiles = await client.supersim.v1.esimProfiles.list({
12
    eid: "",
13
    limit: 20,
14
  });
15

16
  esimProfiles.forEach((e) => console.log(e.sid));
17
}
18

19
listEsimProfile();

1
{
2
  "esim_profiles": [
3
    {
4
      "sid": "HPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
      "iccid": "8988307aaaaaaaaaaaaa",
7
      "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8
      "status": "available",
9
      "eid": "89049032005008882600033489aaaaaa",
10
      "smdp_plus_address": "sm-dp-plus.twilio.com",
11
      "matching_id": null,
12
      "activation_code": null,
13
      "error_code": null,
14
      "error_message": null,
15
      "date_created": "2020-09-01T20:00:00Z",
16
      "date_updated": "2020-09-01T20:00:00Z",
17
      "url": "https://supersim.twilio.com/v1/ESimProfiles/HPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
18
    }
19
  ],
20
  "meta": {
21
    "first_page_url": "https://supersim.twilio.com/v1/ESimProfiles?PageSize=50&Page=0",
22
    "key": "esim_profiles",
23
    "next_page_url": null,
24
    "page": 0,
25
    "page_size": 50,
26
    "previous_page_url": null,
27
    "url": "https://supersim.twilio.com/v1/ESimProfiles?PageSize=50&Page=0"
28
  }
29
}

You may have seen QR codes used to install eSIM profiles on traditional consumer devices such as phones or tablets. The QR code contains the SM-DP+ address and the matching ID of the eSIM profile to claim, if one was generated, in a specific format. This combined SM-DP+ URL and matching ID are used to construct an "activation code" that is formatted the following way with each element separated by a $:

"1${SM-DP+_ADDRESS}${MATCHING_ID}"

To create a QR code containing an eSIM profile's activation code you will need to precede it with LPA:. For example, the following QR code contains this activation code:

LPA:1$TWL.PROD.ONDEMANDCONNECTIVITY.COM$TAB80-FUT45-XKLX8-BFGT6

Expand image