> For the complete documentation index, see [llms.txt](https://en-api.decisiontele.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en-api.decisiontele.com/esim-api/esims/get-esims-with-assigned-packages.md).

# Get eSIMs with Assigned Packages

Retrieve allocated eSIMs together with their package assignments.

### Request

```http
GET /api/v1/esims?scopeBy=package&allocated=true&page=1&perPage=100
Authorization: Bearer <TOKEN>
Accept: application/json
```

| Query parameter    | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `scopeBy`          | Set to `package` to retrieve package assignments.                 |
| `allocated`        | Set to `true` to retrieve allocated eSIMs.                        |
| `page` / `perPage` | Iterate through all pages using the returned pagination metadata. |

### Response

Simplified eSIM item. The example omits activation data and uses an illustrative client-specific price.

```json
{
  "id": "f452f335-4845-4a44-bf4d-261943bf4081",
  "iccid": "<ICCID>",
  "packageEsims": [
    {
      "id": "e693b396-3507-4f32-8604-4352418ddc15",
      "status": "active",
      "usageStartAt": "2026-10-14T15:40:55.759Z",
      "usageExpireAt": "2026-10-21T15:40:55.759Z",
      "usageValue": "1.206621",
      "usageStatus": "In Use",
      "queuePosition": 1,
      "package": {
        "id": "a0966054-2e2f-4e7f-aead-99817f365d1d",
        "name": "Global 3GB 7 days",
        "price": 8.50,
        "dataLimit": 3,
        "limit": 7,
        "limitType": "day"
      }
    }
  ]
}
```

| Field                          | Description                                                            |
| ------------------------------ | ---------------------------------------------------------------------- |
| `id`                           | eSIM identifier (`esimId`); found at `data[].id` in the list response. |
| `iccid`                        | ICCID; store its mapping to `esimId`.                                  |
| `packageEsims[].id`            | Assignment identifier (`packageEsimId`).                               |
| `packageEsims[].package.id`    | Catalog package identifier.                                            |
| `packageEsims[].queuePosition` | Assignment queue position. Evaluate with status and usage fields.      |

**Important:** one eSIM may have multiple `packageEsims` entries. Do not assume `packageEsims[0]` is the only or current package. Use `status`, `queuePosition`, and usage fields to select the relevant assignment.

See **Usage Fields** for allowance, consumption, validity dates, and status mappings.
