CloudeSIM CloudeSIM API
v1.0 Login →

API Reference

Manage eSIM orders and queries programmatically using your API token.

Authentication

All API requests must include your token in the Authorization header as a Bearer token.

Request header 
Authorization: Bearer YOUR_API_TOKEN

You can generate an API token from your dashboard. Tokens are only shown once.

Base URL

https://api.cloud-esim.com/api/v1

Error Format

All error responses follow a consistent format:

application/json 
{
  "success": false,
  "errorMsg": "Insufficient balance. Required: $1.25, available: $0.00"
}

Get Account Balance

Returns your platform USD balance and username.

GET /api/v1/account/balance

Response

200 OK — application/json 
{
  "success": true,
  "data": {
    "username": "agadev",
    "balance": 24.50,
    "currency": "USD"
  }
}

List eSIM Packages

Returns available eSIM packages. All parameters are optional filters.

POST /api/v1/packages

Parameters

Name Type Required Description
locationCode string optional Country or region code (e.g. US, EU)
type string optional Package type (BASE or TOPUP)
packageCode string optional Specific package code to look up
iccid string optional Filter packages compatible with an eSIM ICCID

Response

200 OK — application/json 
{
  "success": true,
  "obj": {
    "packageList": [
      {
        "packageCode": "ESIM_1GB_7D_US",
        "name": "USA 1GB 7 Days",
        "price": 3.50,
        "currencyCode": "USD",
        "duration": 7,
        "volume": 1024,
        "locationCode": "US",
        "type": "BASE"
      }
    ]
  }
}

Order eSIM

Purchase a new eSIM. The cost (with markup) is automatically deducted from your balance.

POST /api/v1/esim/order

Parameters

Name Type Required Description
packageCode string required The package code to purchase
quantity integer optional Number of eSIMs (default: 1)
iccid string optional For compatible package top-ups

Response

200 OK — application/json 
{
  "success": true,
  "obj": {
    "orderNo": "ESA20240001",
    "esimList": [
      {
        "iccid": "89...",
        "ac": "ABCD1234",
        "qrCodeUrl": "https://..."
      }
    ]
  }
}

Query eSIM

Query the status and details of an existing eSIM by ICCID or order number.

POST /api/v1/esim/query

Parameters

Name Type Required Description
iccid string optional eSIM ICCID
orderNo string optional Order number returned on purchase

Response

200 OK — application/json 
{
  "success": true,
  "obj": {
    "esimList": [
      {
        "iccid": "89...",
        "status": "ACTIVE",
        "remainingVolume": 512,
        "expireTime": "2024-12-31"
      }
    ]
  }
}

Top-up eSIM

Add more data to an existing eSIM. The cost is deducted from your balance.

POST /api/v1/esim/topup

Parameters

Name Type Required Description
iccid string required The ICCID of the eSIM to top up
packageCode string required Top-up package code (type: TOPUP)
quantity integer optional Quantity (default: 1)

Response

200 OK — application/json 
{
  "success": true,
  "obj": {
    "orderNo": "ESA20240002"
  }
}

Cancel eSIM Order

Cancel an eSIM. Provide iccid or esimTranNo (at least one required). If successful, the full amount is automatically refunded to your balance.

POST /api/v1/esim/cancel

Parameters

Name Type Required Description
iccid string optional ICCID of the eSIM to cancel
esimTranNo string optional Transaction number (orderNo) from the original order

Response

200 OK — application/json 
{
  "success": true,
  "obj": {
    "orderNo": "ESA20240001"
  }
}