> For the complete documentation index, see [llms.txt](https://docs.giga.store/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giga.store/api/esim-profiles.md).

# eSIM Profiles

An eSIM profile allows access to the mobile data network. The user can install an eSIM using different methods on an eSIM-capable smartphone:

* Scan the Activation Code
* Direct Installation via Universal link (recommended)

### eSIM API Object

Each eSIM profile comes with 

* **uid** - identitier;  used for SDK eSIM download
* **ICCID** - main identifier for end-user support
* **activationCode** - used to install the eSIM
* **IMSI, lastSeen, activatedAt** - additional identifiers for support
* **state** - current state (e.g. INSTALLED)

```
{
    "iccid": "89972123300991848961",
    "imsi": "260060145143896",
    "activationCode": "LPA:1$domain.tld$1234567890ABCDEF123456",
    "appleUniversalLink": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$<SM-DP+ Address>$<Activation Code>",
    "installationUrl": "https://dent.giga.store#/esim/profile?token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI4OTk3MjEyMzMwMDk5MTg0ODk2MSJ9.V34vHdqG6QD9iyCLjIfh2zxsv5MUUjEaOkSw3EY_RVJAxhQQfTeZBfEL_EYwAS9TMNi_Rn6L2Q2cuuI8Ve9zmQ",
    "lastSeen": null,
    "activatedAt": null,
    "state": "RELEASED",
    "uid": "7555cab8-72bc-4e85-b56a-6cdf60e2d6e4",
    "active": true
}
```

### Providing QR code for installation

Once the [First Package](/api/first-package.md) is activated, the returned eSIM can be used to provide a QR code for installing the eSIM.&#x20;

You can use any QR code renderer to generate a QR code using the `activationCode` and provide it to your user via email or through other channels.

The QR code must be scanned with an eSIM-capable device, like an iPhone 14.

<figure><img src="/files/EWQpPzBBHP11cDYwFRV2" alt="" width="251"><figcaption><p>Example QR code of <br>LPA:1$domain.tld$1234567890ABCDEF123456</p></figcaption></figure>

<figure><img src="/files/Kl0pg4s9yRqWrGUmJltf" alt="" width="188"><figcaption><p>iPhone identifies the code as "Mobile Plan"</p></figcaption></figure>

### Direct installation via Universal Links

On Android 10 and iOS 17.4 and above, users can install their eSIM directly on their devices by clicking a simple link.\
\
The Universal Link install method works by adding the unique SMDP+ address and Activation Code as parameters to the universal link URL, which can be tied to a button in your application.\
\
The universal link would look as follows:

| OS      | URL                                                                    | Activation code                       | Universal Link Sample                                                                                         |
| ------- | ---------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Apple   | <https://esimsetup.apple.com/esim\\_qrcode\\_provisioning?carddata=>   | LPA:1$SMDP+\_Address$Activation\_Code | <https://esimsetup.apple.com/esim\\_qrcode\\_provisioning?carddata=LPA:1$SMDP+\\_Address$Activation\\_Code>   |
| Android | <https://esimsetup.android.com/esim\\_qrcode\\_provisioning?carddata=> | LPA:1$SMDP+\_Address$Activation\_Code | <https://esimsetup.android.com/esim\\_qrcode\\_provisioning?carddata=LPA:1$rsp.truphone.com$JQ-209U6H-6I82J5> |

Important Notes for Implementation:

1. URL Casing: The base URL should always be lowercase to ensure compatibility and avoid processing errors.
2. Activation Code: The Activation Code may contain capital letters and should be entered strictly as provided.
3. External Link Configuration: If integrating this link within an app, configure it to open externally. This ensures that the device’s browser handles the activation, adhering to Apple’s setup protocols.

SMDP+ address and Activation Code are provided with this request

`POST /gigastore/activations/register`

### eSIM States

An eSIM can have different states. You can use the eSIM state to guide the user during your user journey.

| State             | Meaning                                         | Comment                                                                     |
| ----------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
| RELEASED          | Not installed on a device                       | Profile ready to be downloaded and installed                                |
| DISABLED          | Installed, but user disabled the eSIM in the OS | Not available for all eSIM profiles / devices                               |
| INSTALLED/ENABLED | Installed and enabled                           | Profile is already installed, and may already be turned on in user's device |
| ERROR             | Something went wrong during installation        | Contact support to replace the profile.                                     |

To receive status updates, use the [eSIM Status](/webhooks/esim-status.md) webhook. The webhook is triggered within a few seconds after the user interaction.