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

# ICCID and card management

> Learn what the ICCID is, how eSIM and physical SIM cards differ, and how to query card status, usage, and renewal eligibility using ICCID-based endpoints.

The ICCID (International Circuit Card Identifier) is the unique identifier for a SIM card — physical or eSIM. Every card issued by an order has its own ICCID. You use the ICCID to look up a card's current status, check how much data has been consumed, determine whether the card is eligible for renewal, and query historical plan data. It is the primary key for all post-order card management.

## eSIM vs physical SIM

MIOeSIM supports both eSIM and physical SIM cards. Both types are ordered through the same endpoint (`POST /api_esim/addEsimOrder`), but they differ in how they are activated and managed.

|                     | eSIM                                                                                                            | Physical SIM                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Form factor**     | Digital profile stored on a device's eUICC chip. No physical card is shipped.                                   | A traditional plastic SIM card shipped to a distribution partner.          |
| **Activation**      | Customer scans a QR code or enters an LPA string (`LPA:1$<sm_dp_address>$<activationCode>`) in device settings. | Customer inserts the physical card into their device.                      |
| **Distribution**    | Activation codes and QR codes are delivered via the API response immediately after ordering.                    | Cards are distributed through a DP (distribution partner).                 |
| **Order parameter** | No `dpId` required.                                                                                             | Include `dpId` in the order request to identify the distribution partner.  |
| **SKU retrieval**   | Use `GET /api_esim/getSkus` or `GET /api_esim/getSkuByGroup`.                                                   | Use `GET /api_esim/getDpSupportSkuInfo?dpId=<id>` to get SKUs for your DP. |

When placing a physical SIM order, pass the `dpId` parameter in the request body. Omitting it will cause the order to fail. Contact MIOeSIM to obtain your `dpId` if you have not already received one.

## ICCID operations

Once you have an ICCID from an order response, you can perform the following operations:

* **Look up renewal options** — retrieve which SKUs and packages are available for an existing card, so you can present renewal choices to your customer before their plan expires.
* **Check current usage** — query how much data has been consumed, when the plan started and ends, and the current activation status of the card.
* **Get historical packages** — retrieve a list of all plans that have been active on this ICCID over time.
* **Query card status** — check whether the card is currently active, disabled, or deleted.
* **Batch query** — retrieve status and usage information for up to 100 ICCIDs in a single request, useful for bulk monitoring.

### ICCID endpoints

| Endpoint                                   | Description                                                                           |
| ------------------------------------------ | ------------------------------------------------------------------------------------- |
| `GET /api_esim/getIccidSupportSku`         | Returns the SKUs available for renewal on this ICCID.                                 |
| `GET /api_esim/getIccidSupportPackageInfo` | Returns the packages available for renewal on this ICCID.                             |
| `GET /api_esim/getESIMDetail`              | Returns full usage data and current status for a single ICCID. Requires IP whitelist. |
| `GET /api_esim/queryIccidInformation`      | Batch query for up to 100 ICCIDs.                                                     |
| `GET /api_esim/getHistoryDetail`           | Returns historical plan records for this ICCID.                                       |

## Card status values

The `dpStatus` field on a card record indicates the current state of the SIM card.

| Value     | Description                                                                             |
| --------- | --------------------------------------------------------------------------------------- |
| `ACTIVE`  | The card is active and the plan is running. Data usage is being tracked.                |
| `Enable`  | The card profile is enabled on the device but the plan may not have started yet.        |
| `Disable` | The card profile has been disabled. The card is not in active use.                      |
| `Delete`  | The card profile has been deleted from the device. The card can no longer be activated. |

Use `dpStatus` to surface card health to your customers and to determine whether a renewal or support action is relevant.

## Checking usage

Call `GET /api_esim/getESIMDetail` with an ICCID to retrieve the full current state of a card, including:

* Data consumed (`usedMB`)
* Plan start and end dates
* Current activation status
* Remaining data

```
GET http://bpm.mioesim.com/api_esim/getESIMDetail?iccid=<iccid>
```

<Warning>
  `getESIMDetail` requires your server's IP address to be on the MIOeSIM whitelist. Calls from non-whitelisted IPs will be rejected. Contact MIOeSIM at [help@mioesim.com](mailto:help@mioesim.com) to have your IP added before using this endpoint.
</Warning>

## Batch querying cards

Call `GET /api_esim/queryIccidInformation` to retrieve status information for multiple ICCIDs in a single request. Pass a comma-separated list of ICCIDs in the request. The endpoint accepts up to **100 ICCIDs per call**.

```
GET https://bpm.mioesim.com/api_esim/queryIccidInformation?iccids=<iccid1>,<iccid2>,...&token=<token>&sign=<sign>
```

The response returns a record for each ICCID in the same order as the input, including each card's current status, plan dates, and data usage. Use this endpoint to efficiently poll a large portfolio of cards — for example, to detect expired plans or cards approaching their data limit — without making individual requests for each ICCID.