Skip to main content
GET
/
api
/
esim
/
my-esims
Get My eSIMs
curl --request GET \
  --url https://api.vellosim.com/api/esim/my-esims \
  --header 'X-API-Key: <api-key>'
{
  "esims": [
    {
      "_id": "esim_64f8a1b2c3d4e5f6a7b8c9d0",
      "packageCode": "US_5GB_30D",
      "packageName": "USA 5GB - 30 Days",
      "transactionId": "esim_1699564800_12345",
      "iccid": "8944500123456789012",
      "qrCodeUrl": "https://vellosim.com/qr/abc123",
      "activationCode": "LPA:1$smdp.address$matchingId",
      "esimStatus": "ACTIVE",
      "data": "5GB",
      "totalVolume": 5368709120,
      "orderUsage": 1073741824,
      "data_usage_remain": 4294967296,
      "validity": 30,
      "activateTime": "2024-10-15T10:30:00Z",
      "expiredTime": "2024-11-14T10:30:00Z",
      "createdAt": "2024-10-15T10:00:00Z",
      "price": 8000,
      "currency": "NGN",
      "packageDetails": {
        "coverage": ["United States"],
        "networkProviders": ["AT&T", "T-Mobile", "Verizon"]
      }
    },
    {
      "_id": "esim_64f8a1b2c3d4e5f6a7b8c9d1",
      "packageCode": "EU_10GB_15D",
      "packageName": "Europe 10GB - 15 Days",
      "transactionId": "esim_1699564900_12346",
      "iccid": "8944500123456789013",
      "qrCodeUrl": "https://vellosim.com/qr/def456",
      "activationCode": "LPA:1$smdp.address$matchingId2",
      "esimStatus": "EXPIRED",
      "data": "10GB",
      "totalVolume": 10737418240,
      "orderUsage": 8589934592,
      "data_usage_remain": 0,
      "validity": 15,
      "activateTime": "2024-09-01T08:00:00Z",
      "expiredTime": "2024-09-16T08:00:00Z",
      "createdAt": "2024-08-31T20:00:00Z",
      "price": 12000,
      "currency": "NGN",
      "packageDetails": {
        "coverage": ["France", "Germany", "Italy", "Spain"],
        "networkProviders": ["Orange", "Vodafone", "T-Mobile"]
      }
    }
  ],
  "total": 25,
  "page": 1,
  "limit": 10,
  "totalPages": 3
}

​
Endpoint

GET /api/esim/my-esims

​
Description

Retrieve a paginated list of all your eSIM orders with optional filtering by status and search.

​
Authentication

​
X-API-Key
string
required
API Key for authentication
YOUR_API_KEY

​
Query Parameters

​
page
number
default:"1"
Page number for pagination
​
limit
number
default:"10"
Number of items per page (max: 100)
​
status
string
Filter by eSIM status:
  • ACTIVE - Currently active eSIMs
  • EXPIRED - Expired eSIMs
  • PENDING - Payment pending
  • FAILED - Failed orders
  • CANCELLED - Cancelled orders
​
search
string
Search by package name, ICCID, or transaction ID

​
Response

​
esims
array
Array of eSIM order objects
​
total
number
Total number of eSIMs matching the filter
​
page
number
Current page number
​
limit
number
Items per page
​
totalPages
number
Total number of pages

​
Example Request

# Get all eSIMs
curl -X GET 'https://api.vellosim.com/api/esim/my-esims' \
  -H "X-API-Key: YOUR_API_KEY"

# Get active eSIMs only
curl -X GET 'https://api.vellosim.com/api/esim/my-esims?status=ACTIVE' \
  -H "X-API-Key: YOUR_API_KEY"

# Search eSIMs
curl -X GET 'https://api.vellosim.com/api/esim/my-esims?search=USA&page=1&limit=20' \
  -H "X-API-Key: YOUR_API_KEY"

​
Example Response

{
  "esims": [
    {
      "_id": "esim_64f8a1b2c3d4e5f6a7b8c9d0",
      "packageCode": "US_5GB_30D",
      "packageName": "USA 5GB - 30 Days",
      "transactionId": "esim_1699564800_12345",
      "iccid": "8944500123456789012",
      "qrCodeUrl": "https://vellosim.com/qr/abc123",
      "activationCode": "LPA:1$smdp.address$matchingId",
      "esimStatus": "ACTIVE",
      "data": "5GB",
      "totalVolume": 5368709120,
      "orderUsage": 1073741824,
      "data_usage_remain": 4294967296,
      "validity": 30,
      "activateTime": "2024-10-15T10:30:00Z",
      "expiredTime": "2024-11-14T10:30:00Z",
      "createdAt": "2024-10-15T10:00:00Z",
      "price": 8000,
      "currency": "NGN",
      "packageDetails": {
        "coverage": ["United States"],
        "networkProviders": ["AT&T", "T-Mobile", "Verizon"]
      }
    },
    {
      "_id": "esim_64f8a1b2c3d4e5f6a7b8c9d1",
      "packageCode": "EU_10GB_15D",
      "packageName": "Europe 10GB - 15 Days",
      "transactionId": "esim_1699564900_12346",
      "iccid": "8944500123456789013",
      "qrCodeUrl": "https://vellosim.com/qr/def456",
      "activationCode": "LPA:1$smdp.address$matchingId2",
      "esimStatus": "EXPIRED",
      "data": "10GB",
      "totalVolume": 10737418240,
      "orderUsage": 8589934592,
      "data_usage_remain": 0,
      "validity": 15,
      "activateTime": "2024-09-01T08:00:00Z",
      "expiredTime": "2024-09-16T08:00:00Z",
      "createdAt": "2024-08-31T20:00:00Z",
      "price": 12000,
      "currency": "NGN",
      "packageDetails": {
        "coverage": ["France", "Germany", "Italy", "Spain"],
        "networkProviders": ["Orange", "Vodafone", "T-Mobile"]
      }
    }
  ],
  "total": 25,
  "page": 1,
  "limit": 10,
  "totalPages": 3
}

​
eSIM Status

StatusDescription
CREATEDeSIM created, not yet activated
ACTIVEeSIM is active and in use
EXPIREDeSIM validity period has ended
PENDINGPayment pending
FAILEDOrder or activation failed
CANCELLEDOrder was cancelled
SUSPENDEDeSIM temporarily suspended

​
Use Cases

Show all eSIMs in a dashboard:
async function displayEsimsDashboard() {
  const { esims, total } = await getMyEsims(1, 20);
  
  esims.forEach(esim => {
    console.log(`${esim.packageName} - ${esim.esimStatus}`);
    console.log(`Data remaining: ${formatBytes(esim.data_usage_remain)}`);
    console.log(`Expires: ${new Date(esim.expiredTime).toLocaleDateString()}\n`);
  });
  
  console.log(`Showing ${esims.length} of ${total} total eSIMs`);
}
Show only currently active eSIMs:
async function getActiveEsimsOnly() {
  const { esims } = await getMyEsims(1, 100, 'ACTIVE');
  return esims;
}

// Display active eSIMs
const activeEsims = await getActiveEsimsOnly();
console.log(`You have ${activeEsims.length} active eSIMs`);
Search for specific eSIMs:
async function findEsim(query) {
  const { esims } = await searchEsims(query);
  
  if (esims.length === 0) {
    console.log('No eSIMs found');
    return null;
  }
  
  return esims;
}

// Search for USA eSIMs
const usaEsims = await findEsim('USA');
Implement pagination in your UI:
async function loadEsimsPage(page) {
  const { esims, totalPages, page: currentPage } = await getMyEsims(page, 10);
  
  renderEsims(esims);
  renderPagination(currentPage, totalPages);
}

// Load next page
function nextPage(currentPage) {
  loadEsimsPage(currentPage + 1);
}

​
Data Usage Formatting

Helper function to format data usage: 
function formatBytes(bytes) {
  if (bytes === 0) return '0 Bytes';
  
  const k = 1024;
  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  
  return Math.round(bytes / Math.pow(k, i) * 100) / 100 + ' ' + sizes[i];
}

// Usage
const remaining = formatBytes(esim.data_usage_remain); // "4.0 GB"

​
Next Steps

Get eSIM Details

Get detailed information for a specific eSIM

Purchase eSIM

Buy a new eSIM package

eSIM Statistics

View your eSIM usage statistics

Integration Guide

Build an eSIM management dashboard