> 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/list-esims.md).

# List eSIMs

Retrieve eSIM inventory and store the identifiers needed for subsequent requests.

### Request

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

To select unallocated inventory during provisioning:

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

| Query parameter    | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `allocated`        | Use `false` for unallocated eSIMs or `true` for allocated eSIMs.     |
| `page` / `perPage` | Pagination controls. Iterate using the returned pagination metadata. |

### Response

Simplified response showing identifier fields only.

```json
{
  "data": [
    {
      "id": "f452f335-4845-4a44-bf4d-261943bf4081",
      "iccid": "<ICCID>"
    }
  ]
}
```

| Field          | Description                      |
| -------------- | -------------------------------- |
| `data[].id`    | Internal `esimId`.               |
| `data[].iccid` | ICCID associated with that eSIM. |

Store the mapping `ICCID -> esimId`. To retrieve package assignments and usage fields, use **Get eSIMs with Assigned Packages**.
