> 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                       | Android Universal Link                                                                                        |
| ------- | ---------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| 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 | Installed and enabled                           |                                               |
| 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.giga.store/api/esim-profiles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.