# Get Started with Super SIM eSIM Profiles for eUICCs ## Traditional SIMs Whether they are in the form of cards or embedded chips, contain connectivity settings for a single connectivity provider. This provider may be a mobile network operator, such as AT\&T, or a company like KORE that leverages networks from all over the world. Regardless of who the provider is, their settings are stored in a **profile**. A traditional SIM's profile is baked in at the manufacturer and cannot be changed. There is a one-to-one correspondence between SIM and profile. ## eSIMs eSIMs may be embedded, but they are not required to be — they are not bound to specific profiles, and the profiles they contain are not fixed in place. On the contrary, eSIMs, unlike traditional SIMs, can contain multiple profiles, switch between them, and download additional profiles over the air. You can think of each eSIM profile as a virtual SIM card. Switching from one profile to another is the digital equivalent of swapping SIM cards. {% hint style="info" %} An eSIM is embodied in a physical unit called an Embedded Universal Integrated Circuit Card (eUICC). For this reason, the term 'eUICC' is often used interchangeably with 'eSIM'. We will use 'eSIM' here. eUICCs are chips and may be integrated into a cellular module or the host device, or even implemented as a SIM card. {% endhint %} There's a clear benefit to this ability: an eSIM-equipped device can switch from one network provider to another just by downloading and activating a new profile. This can happen entirely under the control of the application — the end-user need never know a change has taken place. For remote devices in locations where it is unfeasible to send an engineer to swap SIM cards, it enables connectivity switches.
*An eSIM example: the IoT device, a hire bike, powers up for the first time. It requests and downloads a Super SIM profile to its eSIM, allowing it to connect to its home base over a mobile cellular network.* It is no wonder that device manufacturers are increasingly demanding eSIMs for their connected products. The good news is that KORE fully supports eSIMs, allowing customers who have chosen to incorporate eSIMs into their products to take full advantage of Super SIM's global connectivity via multiple Tier-1 networks. This short guide will introduce you to working with Super SIM and an eSIM-equipped device. You can follow along to set up an eSIM-compatible tablet or phone as a stand-in for your IoT device, providing a clear picture of the device side of the process. However, all the API calls used in the walkthrough and the sequence of steps are the same, whatever hardware your IoT product is based on. *** ## Try it out {% hint style="info" %} If you're ready to implement eSIM Profiles, visit '[How to Use Super SIM eSIM Profiles](https://docs.korewireless.com/supersim/how-to/how-to-use-super-sim-esim-profiles),' which contains more detailed information than this introductory guide and focuses on using profiles with IoT devices. {% endhint %} You can get a clear picture of how Super SIM's eSIM profiles work by trying them out for yourself. Many leading Android devices, such as the Google Pixel 4, 5, and 6, support eSIMs via a built-in eUICC. Additionally, iPad Pros released since 2018, as well as iPads, iPad Airs, and iPad Minis released since 2019, all feature an eUICC as well. These devices all use the consumer eSIM architecture. There are two different types of eSIM profiles, consumer and M2M, and they are not interchangeable. Super SIM currently supports consumer profiles only. {% hint style="danger" %} iOS may not always work well with Super SIM eSIM profiles. Every Super SIM will switch between multiple IMSIs depending on the country in which the device is being used. For some IMSIs, iOS, particularly on iPhones, may prevent you from changing from the APN. If you can't change the APN to `super`, you will not be able to use data. Tools like [Apple Configurator](https://apps.apple.com/app/apple-configurator-2/id1037126344?mt=12) can help you get around this limitation if iOS is preventing you from setting the APN. Unless you need to use iOS, we recommend you try Super SIM profiles on an Android device. {% endhint %} In addition to a mobile device containing an eSIM, you will also need a computer and an API tool to interact with the Super SIM API. The crucial point is that, from an API perspective, the actions you'll perform in the steps below will be the same as those you'll implement to provision the off-the-shelf eUICCs in your IoT devices. *** ## How to prepare and install an eSIM There are several ways to install a Super SIM eSIM profile on your device. Super SIM supports the following methods: [**Activation Code**](#activation-code) uses a code, often embedded in a QR code, which can be read using a device's camera, if it has one, or entered via a keypad. This is a more suitable method for applications built for tablets or phones. It doesn't require you to know the EID of the device that will claim the profile, which any eSIM-capable device can use — though once claimed, the profile can only be used with the device that claimed it. [**Default SM-DP+**](#default-sm-dp) is more typically used by applications that don't need to allow the end-user to set up cellular connectivity, such as traditional IoT applications. The eSIM profile is bound to the eSIM's unique ID (EID), which you must know upfront and can only be used with that specific eSIM. That said, iOS and Android also support it, so we'll show how it's done there, too. ### Activation Code **1. Reserve an eSIM Profile** Choose between the two Super SIM interfaces below: {% tabs %} {% tab title="Super SIM Console" %} a. In the Super SIM Overview page, under the Reserve & Manage eSIM Profiles card, click the Reserve eSIM Profiles link

Reserve eSIM Profiles

b. In the Reserve eSIM Profiles page, reserve a profile by choosing between the two download method, in this example let's select `Generate Matching ID` and enter the quantity or leave at at 1. Click Reserve when you're ready.

Reserve eSIM Profiles

c. This will create a new eSIM profile, with status updating from `Reserving` to `Available` - when refreshed - with information about your new eSimProfile. Make a note of its SID, which will be 32 characters long, starting with `HP`.

eSIM Profiles Page With Available eSIM Profile

{% endtab %} {% tab title="Super SIM API" %} On your computer, enter the following command in a terminal: {% code overflow="wrap" %} ```bash curl -X POST https://supersim.api.korewireless.com/v1/ESimProfiles \ --data-urlencode "GenerateMatchingId=true" \ --header "Authorization: Bearer " ``` {% endcode %} This will create a new [eSimProfile resource](https://docs.korewireless.com/en-us/api/products/supersim/esimprofile-resource) — the API's representation of the eSIM profile you are creating. The command will display information about the new eSimProfile. The command above will display information about the new eSimProfile. Make a note of its SID, which will be 32 characters long, starting with `HP`. {% endtab %} {% endtabs %} **2. Confirm the new eSIM Profile's readiness** {% tabs %} {% tab title="Super SIM Console" %} a. Click the eSIM Profile SID to load the eSIM Profile Details page

eSIM Profile Details Page

In the eSIM Profile displayed, check the value of the `status` key. When it is `available`, you're ready for the next step, but you may see `reserving` instead. This means KORE is still in the process of setting up the new eSIM profile. Wait a couple of minutes and try again. In a real-world application, you'd add a callback URL to the API call. KORE will then post notifications to this URL whenever the eSimProfile resource's status changes and when it is eventually downloaded to an eSIM. {% endtab %} {% tab title="Super SIM API" %} Run the following command: {% tabs %} {% tab title="Request" %} {% code overflow="wrap" %} ```bash curl -L "https://supersim.api.korewireless.com/v1/ESimProfiles/" \ --header "Authorization: Bearer " ``` {% endcode %} {% endtab %} {% tab title="Response" %} ```json { "sid": "HPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "account_sid": "ACnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn", "eid": "nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn", "status": "available", "iccid": "nnnnnnnnnnnnnnnnnnnn", "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "smdp_plus_address": "twl.prod.ondemandconnectivity.com", "matching_id": null, "activation_code": null, "date_created": "2024-10-07T16:23:13.927149Z", "date_updated": "2024-10-07T16:23:15.614392Z", "url": "https://supersim.api.korewireless.com/v1/ESimProfiles/HPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ``` {% endtab %} {% endtabs %} In the JSON displayed, check the value of the `status` key. When it is `available`, you're ready for the next step, but you may see `reserving` instead. This means KORE is still in the process of setting up the new eSIM profile. Wait a couple of minutes and try again. In a real-world application, you'd add a callback URL to the API call. KORE will then post notifications to this URL whenever the eSimProfile resource's status changes and when it is eventually downloaded to an eSIM. {% endtab %} {% endtabs %} **3. Get your eSIM Profile's Sim resource SID** When the eSIM Profile has been reserved, KORE creates a [Sim resource](https://docs.korewireless.com/en-us/api/products/supersim/sim-resource) to represent the eSIM in your device. Note down the new SIM's SID, which is the value of the SIM SID |`sim_sid` key in the output from the previous step. Make a note too of the values of the SM-DP+ Address | `smdp_plus_address key` and Matching ID | `matching_id` keys. If you are using the API, you will need to use these values shortly to construct the Activation Code; otherwise, they are already available to you in the UI. **4. Assign the Sim resource to a Fleet and activate it** If you don't already have a [Fleet resource](https://docs.korewireless.com/en-us/api/products/supersim/fleet-resource), you will need to create one now and set up its Network Access Profile — a list of global cellular networks to which its member SIMs can connect. If you need assistance, refer to our Network Access Profiles guide, and we will guide you through the process. Whether you use an existing Fleet or create a new one, you'll need its SID, which [you can grab from Console](https://supersim.korewireless.com/supersim/fleets). {% tabs %} {% tab title="Request" %} ```bash curl -L -X POST "https://supersim.api.korewireless.com/v1/Sims/" \ --data-urlencode "Fleet=" \ --data-urlencode "Status=active" \ --header "Authorization: Bearer " ``` {% endtab %} {% tab title="Response" %} ```json { "sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "unique_name": "", "status": "active", "iccid": "nnnnnnnnnnnnnnnnnnnn", "fleet_sid": "HFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "date_created": "2024-10-07T16:23:15Z", "date_updated": "2024-11-18T18:36:20Z", "url": "https://supersim.api.korewireless.com/v1/Sims/HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "links": { "billing_periods": "https://supersim.api.korewireless.com/v1/Sims/HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/BillingPeriods", "sim_ip_addresses": "https://supersim.api.korewireless.com/v1/Sims/HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IpAddresses" } } ``` {% endtab %} {% endtabs %} **5. Create the Activation Code** Take the `smdp_plus_address` and `matching_id` values you got in [Step 3](https://www.twilio.com/docs/iot/supersim/get-started-with-super-sim-and-esim-profiles#3-get-your-esim-profiles-sim-resource-sid), and paste them into a string as follows: ``` 1$$ ``` This is your eSimProfile's Activation Code. You can enter this manually into your device, but it's more fun to convert it into a QR code that your device can scan. To do so, first add `LPA:` to the start of the string — this tells the QR code scanner how to handle the decoded code: ``` LPA:1$$ ``` Paste the complete string into any QR code generation software. There are many free services on the web, or you can use an API like Google's: {% code overflow="wrap" %} ```bash curl -X POST https://chart.googleapis.com/chart -d cht=qr -d chs=256x256 -d chl='LPA:1$$' -o qr-code.png ``` {% endcode %} This will save a QR code graphic in your current working directory. Open it up so it's visible on your screen. **6. Add a new cellular data plan** Go to your mobile device. **Android** {% hint style="danger" %} Due to the numerous differences between Android versions and the OS's implementation by phone and tablet manufacturers, the following references to sections, pages, and controls in the Android UI may not fully match those on your device. However, if you find similar items, use those. {% endhint %} 1. Go to **Settings > Network and Internet**. 2. In the **SIMs** section, tap the **+** icon on the right-hand side of the screen. 3. On the **Connect to Mobile Network** page, tap **Download a SIM instead?**. 4. You'll be asked if you want to use two SIMs — tap **Yes**. 5. On the **Download your SIM** page, just tap **Next**. 6. Scan the QR code displayed on your computer screen. 7. On the **Use** page, tap **Download**. 8. On the **Download finished** page, tap **Settings**. 9. On the **SIMs** page, under **DOWNLOADED SIM**, tap **Inactive**. 10. On the next page, turn the **Use SIM** toggle on. 11. You'll be asked if you want to turn on the SIM — tap **Yes**. 12. You'll be asked to select a SIM for mobile data — select your eSIM. This may be number 1 or number 2, depending on your device, and whether it also has a physical SIM fitted. 13. Finally, on the next screen, turn the **Roaming** toggle on. **iOS** 1. Go to **Settings > Mobile Data** or **Settings > Cellular Data**. Which of these you'll see will depend on your region. 2. Scroll down and tap **Add Data Plan** or **Add Cellular Plan**. If you're working with a new device, you'll see a list of network providers, but just tap **Other…**. 3. Scan the QR code displayed on your computer screen. 4. On the **Add Data Plan** panel, tap the **Add Data Plan** or **Add Cellular Plan** button. 5. There will be a short period while the plan is downloaded and activated. The main **Mobile Data** settings will be disabled while activation is taking place. **7. Enter the Super SIM APN** **Android** 1. Go to **Settings > Mobile Networks > Advanced**. 2. Scroll down and tap **Access Point Names**. 3. Tap the three-dot menu icon and select "New APN." 4. Tap **Name**, enter `KORE` in the pop-up, then tap **OK**. 5. Tap **APN**, enter `super` in the pop-up, then tap **OK**. 6. Tap the three-dot menu icon and select "Save." 7. In the list of APNs, make sure `KORE` is selected. **iOS** 1. Go to **Settings > Mobile Data** or **Settings > Cellular Data**. Which of these you'll see will depend on your region. 2. Tap on **Mobile Data Options** or **Cellular Data Options**. Again, which of these you see will depend on your region. 3. Enable roaming by turning on the **Data Roaming** toggle. 4. Go back to the **Mobile Data** or **Cellular Data** screen and tap on **APN Settings**. 5. Enter `super` in the first **APN** field. Don't enter a username or password. And you are done. Your device's eSIM will now connect to the Internet via the KORE Distributed IoT Mobile Core and any of the cellular networks worldwide that you have assigned to the Network Access Profile associated with your eSIM's Fleet. Make sure the device's WiFi connectivity is turned off and try visiting some websites. If you are not interested in the Default SM-DP+ profile installation method, you can [jump to the last section](#next-steps). #### Default SM-DP+ **1. Find your device's EID.** Go to your mobile device. **Android** {% hint style="danger" %} Due to the numerous differences between Android versions and the OS's implementation by phone and tablet manufacturers, the following references to sections, pages, and controls in the Android UI may not fully match those on your device. However, if you find similar items, use those. {% endhint %} 1. Open the device's **Settings** app. 2. Tap **Phone > SIM status**, and scroll down to **EID**. **iOS** 1. At the home screen, tap on **Settings**. 2. Go to **General > About** and scroll down to **EID**. Write down your device's EID — you'll need it in the next step — or keep the unit turned on beside you. **2. Reserve an eSIM Profile for your device's eSIM** On your computer, enter the following command in a terminal, making sure you replace `` with the value you noted down in Step 1. Enter it carefully, as it's a 32-digit number. {% code overflow="wrap" %} ```bash curl -L -X POST 'https://supersim.api.korewireless.com/v1/ESimProfiles' \ --data-urlencode "Eid=" \ --header "Authorization: Bearer " ``` {% endcode %} This will create a new [eSimProfile resource](https://docs.korewireless.com/en-us/api/products/supersim/esimprofile-resource) — the API's representation of the eSIM profile you are creating. The command will display information about the new eSimProfile. Make a note of its SID, which will be 32 characters long, starting with `HP`. We'll use this value in the next step. **3. Confirm the new eSIM profile's readiness** Run the following command: {% tabs %} {% tab title="Request" %} ```bash curl -L "https://supersim.api.korewireless.com/v1/ESimProfiles/" --header "Authorization: Bearer " ``` {% endtab %} {% tab title="Response" %} ```json { "sid": "HPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "account_sid": "ACnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn", "eid": "nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn", "status": "available", "iccid": "nnnnnnnnnnnnnnnnnnnn", "sim_sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "smdp_plus_address": "twl.prod.ondemandconnectivity.com", "matching_id": null, "activation_code": null, "date_created": "2024-10-07T16:23:13.927149Z", "date_updated": "2024-10-07T16:23:15.614392Z", "url": "https://supersim.api.korewireless.com/v1/ESimProfiles/HPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ``` {% endtab %} {% endtabs %} In the JSON displayed, check the value of the `status` key. When it is `available`, you're ready for the next step, but you may see `reserving` instead. This means KORE is still in the process of setting up the new eSIM profile for the specified EID. Wait a couple of minutes and try again. In a real-world application, you'd add a callback URL to the API call. KORE will post notifications to this URL whenever the eSimProfile resource's status changes and when it is eventually downloaded to its target eSIM. **4. Get your eSIM profile's Sim resource SID** When the eSIM profile has been reserved, KORE creates a [Sim resource](https://docs.korewireless.com/en-us/api/products/supersim) to represent the eSIM in your device. From this point, you'll use this Sim resource just like any other Super SIM. The new Sim's SID is the value of the `sim_sid` key in the output from Step 3, above. Make a note of it; you'll use it in a moment to activate it and add it to a Fleet. In addition to the `sim_sid` key, grab the value of the `smdp_plus_address` key. This is the address of the server your device will contact to download its new eSIM Profile. **5. Assign the Sim resource to a Fleet and activate it** If you don't already have a [Fleet resource](https://docs.korewireless.com/en-us/api/products/supersim/fleet-resource), you'll need to create one now and set up its Network Access Profile — the list of global cellular networks to which its member SIMs can connect. If you need assistance, [jump to our Network Access Profiles guide](https://docs.korewireless.com/en-us/supersim/how-to/understanding-network-access-profiles), which will show you how to do this. Whether you use an existing Fleet or create a new one, you'll need its SID, which [you can grab from Console](https://supersim.korewireless.com/supersim/fleets). Run the following command to add the eSIM to a Fleet and to activate it. Just replace `` with the Sim SID you retrieved in the previous step, and `` with the target Fleet's SID, don't forget ``: {% tabs %} {% tab title="Request" %} ```bash curl -L -X POST "https://supersim.api.korewireless.com/v1/Sims/" --data-urlencode "Fleet=" \ --data-urlencode "Status=active" \ --header "Authorization: Bearer " ``` {% endtab %} {% tab title="Response" %} ```json { "sid": "HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "unique_name": "", "status": "active", "iccid": "nnnnnnnnnnnnnnnnnnnn", "fleet_sid": "HFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "date_created": "2024-10-07T16:23:15Z", "date_updated": "2024-11-18T18:36:20Z", "url": "https://supersim.api.korewireless.com/v1/Sims/HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "links": { "billing_periods": "https://supersim.api.korewireless.com/v1/Sims/HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/BillingPeriods", "sim_ip_addresses": "https://supersim.api.korewireless.com/v1/Sims/HSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IpAddresses" } } ``` {% endtab %} {% endtabs %} **6. Add a new cellular data plan** Go back to your mobile device. **Android** 1. the Open the device's **Settings** app. 2. Go to **Network and Internet > SIMs**, and tap the **+** icon on the right-hand side of the screen. 3. Tap **Download a SIM instead?** at the bottom of the screen. 4. On the **Use 2 SIMs?** panel that will appear, tap **Yes**. 5. On the **Download your SIM** page, tap **Next**. 6. On the **Scan QR code from network** page, tap **Need Help?** at the bottom. 7. On the **Help adding a network page**, find and tap the **Enter it manually** link. 8. On the next screen, enter the URL you received in Step 2, above, then tap **Continue**. 9. You'll be asked if you want to use the eSIM — tap **Download**. 10. There will be a short period while the eSIM profile is downloaded. 11. On the **Download Finished** screen, tap **Settings**. 12. Back at the **SIMs** page, tap the downloaded SIM. 13. Switch the **Use SIM** toggle to on, and then confirm when asked by tapping **Yes**. 14. When asked, select the eSIM for data. 15. Make sure the eSIM's **Mobile data** and **Roaming** toggles are on. **iOS** 1. Go to **Settings > Mobile Data** or **Settings > Cellular Data**. Which of these you'll see will depend on your region. 2. Scroll down and tap **Add Data Plan** or **Add Cellular Plan**. If you're working with a new device, you'll see a list of network providers, but just tap **Other...**. 3. The iOS UI is designed to scan a QR code from an operator, but you should instead tap **Enter Details Manually** at the bottom of the screen. 4. On the **Enter Activation Code** panel, enter the value of the `smdp_plus_address` key you got earlier into the **SM-DP+ Address** field. Leave the other two fields blank. 5. Tap **Next**. 6. On the **Add Data Plan** panel, tap the **Add Data Plan** or **Add Cellular Plan** button. 7. There will be a short period while the plan — the eSIM profile, in other words — is downloaded and activated. The **Mobile Data** settings will be disabled while activation is taking place. **7. Enter the Super SIM APN** **Android** 1. Go to **Settings > Mobile Networks > Advanced**. 2. Scroll down and tap **Access Point Names**. 3. Tap the three dots menu icon and select **New APN**. 4. Tap **Name**, enter `KORE` in the pop up, then tap **OK**. 5. Tap **APN**, enter `super` in the pop up, then tap **OK**. 6. Tap the three dots menu icon and select **Save**. 7. In the list of APNs, make sure `KORE` is selected. **iOS** 1. Go to **Settings > Mobile Data** or **Settings > Cellular Data**. Which of these you'll see will depend on your region. 2. Tap on **Mobile Data Options** or **Cellular Data Options**. Again, which of these you see will depend on your region. 3. Enable roaming by turning on the **Data Roaming** toggle. 4. Go back to the **Mobile Data** or **Cellular Data** screen and tap on **APN Settings**. 5. Enter `super` in the first **APN** field. Don't enter a username or password. And you're done. Your device's eSIM will now connect to the Internet via the KORE Distributed IoT Mobile Core and any of the cellular networks worldwide that you have assigned to the Network Access Profile associated with your eSIM's Fleet. Ensure the device's Wi-Fi connectivity is turned off, and then try visiting some websites. *** ## Next steps In this tutorial, that device was a mobile phone or tablet, but it could have been any IoT device that you or your end-users will deploy. It works just the same way. You can take any off-the-shelf eUICC hardware compatible with the consumer eSIM profile specification, create and install a Super SIM eSIM profile onto it, and by doing so, allow it to connect through mobile networks across the globe. We can't wait to see what products you build and connect.