> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dancity.app/llms.txt
> Use this file to discover all available pages before exploring further.

# eSIM

> Browse regions and packages, purchase an eSIM, and manage active eSIMs

## Overview

Dancity eSIMs give your users data connectivity in 150+ countries without swapping a physical SIM. The eSIM flow is:

1. Browse **regions** to find the destination country or region
2. Browse **packages** for that region to see data, validity, and price
3. **Purchase** the eSIM — the user installs it on their device via a QR code
4. Optionally **top up** an existing eSIM with additional data

## Authentication

All eSIM endpoints use your merchant API key only.

```http theme={null}
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

***

## Step 1 — Browse regions

```
GET /api/v1/esim/regions
```

| Query param | Type | Description |
| - | - | - |
| `type` | number | `1` = single-country, `2` = multi-country/regional |

```bash cURL theme={null}
# Single-country eSIMs
curl -sS "https://api.dancity.app/api/v1/esim/regions?type=1" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://api.dancity.app/api/v1/esim/regions?type=1",
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const { data } = await res.json();
// data = [{ regionCode: "NG", name: "Nigeria" }, ...]
```

```python Python theme={null}
import requests, os

res = requests.get(
    "https://api.dancity.app/api/v1/esim/regions",
    params={"type": 1},
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
```

***

## Step 2 — Browse packages for a region

```
GET /api/v1/esim/packages
```

| Query param | Type | Required | Description |
| - | - | - | - |
| `regionCode` | string | ✓ | Region code from `/esim/regions` (e.g. `"NG"`) |
| `regionType` | string | | Region `type` from the regions response: `"country"` (single country, default) or `"multi-country"` (regional bundle). Pass the same value as the region you selected. |
| `type` | string | | `"BASE"` = new eSIM install, `"TOPUP"` = add data to existing eSIM (default `"BASE"`) |

```bash cURL theme={null}
curl -sS "https://api.dancity.app/api/v1/esim/packages?regionCode=NG&type=BASE" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://api.dancity.app/api/v1/esim/packages?regionCode=NG&type=BASE",
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const { data } = await res.json();
// data = [{ packageCode: "...", data: "1GB", validity: "30 days", price: 5.00 }]
```

```python Python theme={null}
import requests, os

res = requests.get(
    "https://api.dancity.app/api/v1/esim/packages",
    params={"regionCode": "NG", "type": "BASE"},
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
```

***

## Step 3 — Purchase eSIM

```
POST /api/v1/esim/purchase
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `packageCode` | string | ✓ | Package code from `/esim/packages` or `/esim/topup-packages` |
| `customerRef` | string | | Your internal reference ID |
| `iccid` | string | | ICCID of existing eSIM — **required for TOPUP** packages |

```bash cURL theme={null}
curl -sS -X POST "https://api.dancity.app/api/v1/esim/purchase" \
  -H "Authorization: Bearer $DANCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "packageCode": "NG-1GB-30D",
    "customerRef": "ESIM-REF-001"
  }'
```

```javascript Node.js theme={null}
const res = await fetch("https://api.dancity.app/api/v1/esim/purchase", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    packageCode: "NG-1GB-30D",
    customerRef: "ESIM-REF-001",
  }),
});
const data = await res.json();
// data.transactionId → use for status check
```

```python Python theme={null}
import requests, os

res = requests.post(
    "https://api.dancity.app/api/v1/esim/purchase",
    headers={
        "Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"packageCode": "NG-1GB-30D", "customerRef": "ESIM-REF-001"},
)
print(res.json())
```

***

## Top up an existing eSIM

When a user's eSIM is running low on data, list compatible add-on packages using its **ICCID** (the SIM identifier assigned after the first purchase).

```
GET /api/v1/esim/topup-packages
```

### Query parameters

| Param | Type | Required | Description |
| - | - | - | - |
| `iccid` | string | ✓ | ICCID of the active eSIM — from purchase details, `GET /api/v1/esim/my-esims`, or `GET /api/v1/esim/details/{transactionId}` |

```bash cURL theme={null}
curl -sS "https://api.dancity.app/api/v1/esim/topup-packages?iccid=8960000000000000001" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const iccid = "8960000000000000001";
const res = await fetch(
  `https://api.dancity.app/api/v1/esim/topup-packages?iccid=${encodeURIComponent(iccid)}`,
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const { data } = await res.json();
// data.packages → top-up options; data.exchangeRate → USD→NGN rate
```

```python Python theme={null}
import requests, os

res = requests.get(
    "https://api.dancity.app/api/v1/esim/topup-packages",
    params={"iccid": "8960000000000000001"},
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
packages = res.json()["data"]["packages"]
```

### Sample response

```json theme={null}
{
  "success": true,
  "message": "eSIM topup packages fetched successfully",
  "data": {
    "packages": [
      {
        "packageCode": "NG-500MB-7D-TOP",
        "name": "Nigeria 500MB Top-Up",
        "description": "Add 500MB valid for 7 days",
        "price": 0.62,
        "currency": "USD",
        "volume": 524288000,
        "duration": 7,
        "type": "TOPUP",
        "regionCode": "NG",
        "priceInNaira": 1005
      }
    ],
    "exchangeRate": 1620
  }
}
```

Then purchase the selected package with `POST /api/v1/esim/purchase` using the returned `packageCode`.

***

## Fetch eSIMs

List active eSIMs on the merchant account. Each row includes the **ICCID** (needed for top-ups), package details, and activation status.

```
GET /api/v1/esim/my-esims
```

### Query parameters

| Param | Type | Description |
| - | - | - |
| `page` | integer | Page number (default `1`) |
| `limit` | integer | Results per page (default `20`) |

```bash cURL theme={null}
curl -sS "https://api.dancity.app/api/v1/esim/my-esims?page=1&limit=20" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://api.dancity.app/api/v1/esim/my-esims?page=1&limit=20",
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const { data } = await res.json();
// data.esims → array of eSIMs; data.pagination → page info
```

```python Python theme={null}
import requests, os

res = requests.get(
    "https://api.dancity.app/api/v1/esim/my-esims",
    params={"page": 1, "limit": 20},
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
esims = res.json()["data"]["esims"]
```

### Sample response

```json theme={null}
{
  "success": true,
  "message": "User eSIMs fetched successfully",
  "data": {
    "esims": [
      {
        "transactionId": "6a1c50347d0125d168aa32da",
        "tranxId": "DNTY4364368AOMYD",
        "packageCode": "CKH513",
        "packageName": "Qatar 1GB 7Days",
        "packageVolume": 1073741824,
        "packageDuration": 7,
        "regionCode": "QA",
        "amount": 2835,
        "currency": "NGN",
        "iccid": "8948010010013845234",
        "qrCodeUrl": "https://p.qrsim.net/4a8cf5af5f1c48e0b44f8eaf3af20220.png",
        "activationCode": "LPA:1$rsp-eu.simlessly.com$72056D3B588B49B4903120FC95BB96A4",
        "imsi": "260010183468325",
        "smdpAddress": null,
        "status": "GOT_RESOURCE",
        "dataUsageRemaining": 1073741824,
        "purchasedAt": "2026-05-31T15:13:56.436Z"
      },
      {
        "transactionId": "6a12d0d366a638d7d9e402a9",
        "tranxId": "DNTY003519MQ5RPN",
        "packageCode": "P0Q24KI1C",
        "packageName": "Nigeria 100MB 7Days",
        "packageVolume": 104857600,
        "packageDuration": 7,
        "regionCode": "NG",
        "amount": 975,
        "currency": "NGN",
        "iccid": "8948010010014447758",
        "qrCodeUrl": "https://p.qrsim.net/6d17f9164c9c4ad3a97ec890eac4f01b.png",
        "activationCode": "LPA:1$rsp-eu.simlessly.com$537A63701D1A4699ADB0A3206EE4CEA6",
        "imsi": "260010183528577",
        "smdpAddress": null,
        "status": "GOT_RESOURCE",
        "dataUsageRemaining": 104857600,
        "purchasedAt": "2026-05-24T10:20:03.519Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "totalPages": 1,
      "hasPrevious": false,
      "hasNext": false
    }
  }
}
```

***

## Get eSIM details

Fetch QR code, ICCID, activation code, and status for a purchased eSIM. Use this to display the install QR code to your customer or to retrieve the ICCID for top-ups.

```
GET /api/v1/esim/details/{transactionId}
```

### Path parameter

| Param | Description |
| - | - |
| `transactionId` | Mongo `_id`, `tranxId` (e.g. `DNTY8374056F678V`), or `customerRef` from the eSIM purchase |

```bash cURL theme={null}
curl -sS "https://api.dancity.app/api/v1/esim/details/DNTY8374056F678V" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  `https://api.dancity.app/api/v1/esim/details/${transactionId}`,
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const { data } = await res.json();
// data.esim.qrCodeUrl or data.esim.activationCode → show to customer
// data.esim.iccid → use for top-ups
```

```python Python theme={null}
import requests, os

res = requests.get(
    f"https://api.dancity.app/api/v1/esim/details/{transaction_id}",
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
esim = res.json()["data"]["esim"]
```

### Sample response

```json theme={null}
{
  "success": true,
  "message": "eSIM details fetched successfully",
  "data": {
    "iccid": "8948010010013845234",
    "imsi": "260010183468325",
    "qrCodeUrl": "https://p.qrsim.net/4a8cf5af5f1c48e0b44f8eaf3af20220.png",
    "activationCode": "LPA:1$rsp-eu.simlessly.com$72056D3B588B49B4903120FC95BB96A4",
    "status": "GOT_RESOURCE",
    "totalVolume": 1073741824,
    "totalDuration": 7,
    "validityRemaining": 7,
    "dataUsageRemaining": 1073741824,
    "packageDetails": {
      "name": "Qatar 1GB 7Days",
      "code": "CKH513",
      "volume": 1073741824,
      "duration": 7,
      "location": "QA",
      "price": 1.7115,
      "currency": "USD",
      "locationLogo": "https://flagcdn.com/w320/qa.png",
      "description": "Qatar 1GB 7Days",
      "speed": "3G/4G/5G",
      "coverage": [
        {
          "locationName": "Qatar",
          "locationLogo": "https://flagcdn.com/w320/qa.png",
          "locationCode": "QA",
          "operatorList": [
            {
              "operatorName": "ooredoo",
              "networkType": "5G"
            }
          ]
        }
      ]
    },
    "createdAt": "2026-05-31T15:13:57.571Z",
    "expiredAt": "2026-11-27T15:13:58.000Z"
  }
}
```

***

## Full purchase flow

```
1. GET /esim/regions?type=1
   → user selects destination country → note regionCode

2. GET /esim/packages?regionCode=NG&type=BASE
   → user selects data package → note packageCode

3. POST /esim/purchase { packageCode, customerRef? }
   → note transactionId

4. GET /esim/details/{transactionId}
   → display QR code to user for device installation

5. (Optional) GET /esim/topup-packages?iccid={iccid}
   → user selects top-up package → POST /esim/purchase with packageCode
```

> [!TIP]
>
> Save the `transactionId` after purchase. Use `GET /esim/details/{transactionId}` to retrieve and re-display the QR code if the user needs it again.

## Next steps

* [Transactions: requery a purchase](https://docs.dancity.app/guides/transactions.md)
* [Wallet: check balance before purchase](https://docs.dancity.app/guides/wallet.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.