Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vellosim.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Retrieve all eSIMs purchased by your users with support for pagination, filtering by status or region, and search functionality. This endpoint is essential for building eSIM management dashboards and customer portals.

​
Quick Start

async function getAllEsims(page = 1, limit = 20) {
  const response = await fetch(
    `https://api.vellosim.com/api/esim/my-esims?page=${page}&limit=${limit}`,
    {
      method: 'GET',
      headers: {
        'X-API-Key': `API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  const data = await response.json();
  return data;
}

// Usage
const result = await getAllEsims(1, 20);
console.log(`Total eSIMs: ${result.total}`);
console.log(`eSIMs on this page: ${result.esims.length}`);

​
Query Parameters

ParameterTypeDefaultDescription
pagenumber1Page number for pagination
limitnumber10Number of items per page (max: 100)
The API returns complete eSIM objects with all details including QR codes, activation codes, and package information. Use client-side filtering for status, region, or search functionality.

​
Response Format

{
  "esims": [
    {
      "_id": "6912628b56d7f09edabbaf41",
      "packageCode": "CKH513",
      "orderNo": "B25111022090003",
      "transactionId": "esim_1762812553430_6398",
      "esimTranNo": "25111022090003",
      "iccid": "8937204017176061359",
      "imsi": "260010199691215",
      "msisdn": "",
      "ac": "LPA:1$rsp-eu.simlessly.com$D10983C0AE7444A8BA35FB8214410E5A",
      "qrCodeUrl": "https://p.qrsim.net/c78f6799d2c440dea108147a5e3a192a.png",
      "shortUrl": "https://p.qrsim.net/c78f6799d2c440dea108147a5e3a192a",
      "smdpStatus": "RELEASED",
      "eid": "",
      "activeType": "2",
      "expiredTime": "2026-05-09T22:09:15.000Z",
      "totalVolume": 1073741824,
      "totalDuration": 7,
      "durationUnit": "DAY",
      "orderUsage": 0,
      "data_usage_remain": 1073741824,
      "validity_usage_remain": 7,
      "pin": "1833",
      "puk": "78569098",
      "apn": "plus",
      "esimStatus": "GOT_RESOURCE",
      "smsStatus": 0,
      "dataType": 1,
      "packageDetails": {
        "name": "Qatar 1GB 7Days",
        "code": "CKH513",
        "volume": 1073741824,
        "duration": 7,
        "location": "QA",
        "price": 8640,
        "currency": "NGN",
        "locationLogo": "https://flagcdn.com/w320/qa.png",
        "description": "Qatar 1GB 7Days",
        "speed": "3G/4G/5G",
        "coverage": [
          {
            "locationName": "Qatar",
            "locationLogo": "https://flagcdn.com/w320/qa.png",
            "locationCode": "QA",
            "operatorList": [
              {
                "operatorName": "ooredoo",
                "networkType": "5G"
              },
              {
                "operatorName": "Vodafone",
                "networkType": "5G"
              }
            ]
          }
        ]
      },
      "isActive": true,
      "createdAt": "2025-11-10T22:09:15.070Z",
      "updatedAt": "2025-11-10T22:09:15.533Z",
      "user": "69120363ed042b4afb7aca90",
      "transactionRef": "6912628a56d7f09edabbaf3d",
      "__v": 0
    }
  ],
  "total": 3,
  "page": 1,
  "limit": 10,
  "totalPages": 1
}

​
Response Fields

FieldTypeDescription
esimsarrayArray of eSIM objects with complete details
esims[]._idstringUnique eSIM identifier (use this for esimId in top-ups)
esims[].iccidstringIntegrated Circuit Card ID
esims[].transactionIdstringPurchase transaction identifier
esims[].orderNostringOrder reference number
esims[].acstringFull LPA activation code
esims[].qrCodeUrlstringQR code image URL
esims[].shortUrlstringShort URL to QR code page
esims[].esimStatusstringeSIM status (GOT_RESOURCE, etc.)
esims[].totalVolumenumberTotal data in bytes
esims[].data_usage_remainnumberRemaining data in bytes
esims[].orderUsagenumberData used in bytes
esims[].totalDurationnumberTotal validity period
esims[].validity_usage_remainnumberRemaining validity days
esims[].durationUnitstringTime unit (DAY, MONTH, etc.)
esims[].expiredTimestringISO 8601 expiry timestamp
esims[].pinstringSIM PIN code
esims[].pukstringSIM PUK code
esims[].apnstringAccess Point Name
esims[].packageDetailsobjectComplete package information with coverage
esims[].isActivebooleanWhether eSIM is active
esims[].createdAtstringCreation timestamp
esims[].updatedAtstringLast update timestamp
totalnumberTotal count of all eSIMs
pagenumberCurrent page number
limitnumberItems per page
totalPagesnumberTotal number of pages