Skip to main content
GET
/
api
/
esim
/
:esimId
{
  "_id": "esim_64f8a1b2c3d4e5f6a7b8c9d0",
  "packageCode": "US_5GB_30D",
  "packageName": "USA 5GB - 30 Days",
  "orderNo": "ORD-2024-001234",
  "transactionId": "esim_1699564800_12345",
  "esimTranNo": "ESIM-TXN-567890",
  "iccid": "8944500123456789012",
  "imsi": "310260123456789",
  "msisdn": null,
  "ac": "ABC-123-DEF-456",
  "qrCodeUrl": "https://vellosim.com/qr/abc123",
  "shortUrl": "https://vls.to/abc123",
  "activationCode": "LPA:1$smdp.gsma.com$ABC-123-DEF-456",
  "smdpAddress": "smdp.gsma.com",
  "matchingId": "ABC-123-DEF-456",
  "eid": "89049032123456789012345678901234",
  "smdpStatus": "INSTALLED",
  "activeType": "AUTOMATIC",
  "activateTime": "2024-10-15T10:30:00Z",
  "expiredTime": "2024-11-14T10:30:00Z",
  "esimStatus": "ACTIVE",
  "data": "5GB",
  "totalVolume": 5368709120,
  "orderUsage": 1073741824,
  "data_usage_remain": 4294967296,
  "validity": 30,
  "durationUnit": "DAY",
  "totalDuration": 30,
  "validity_usage_remain": 25,
  "pin": null,
  "puk": null,
  "apn": "internet",
  "smsStatus": 0,
  "dataType": 1,
  "price": 8000,
  "currency": "NGN",
  "packageDetails": {
    "coverage": ["United States"],
    "networkProviders": ["AT&T", "T-Mobile", "Verizon"],
    "dataType": "Data Only",
    "speed": "4G/5G"
  },
  "isActive": true,
  "createdAt": "2024-10-15T10:00:00Z",
  "updatedAt": "2024-11-05T08:15:00Z"
}

Endpoint

GET /api/esim/:esimId

Description

Retrieve complete details for a specific eSIM order including QR code, activation codes, data usage, and network information.

Authentication

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

Path Parameters

esimId
string
required
The unique identifier of the eSIM order

Response

_id
string
eSIM unique identifier
packageCode
string
Package code of the purchased eSIM
packageName
string
Display name of the package
transactionId
string
Transaction ID for the purchase
iccid
string
ICCID (Integrated Circuit Card Identifier)
imsi
string
IMSI (International Mobile Subscriber Identity)
msisdn
string
Phone number assigned to the eSIM (if applicable)
qrCodeUrl
string
URL to the QR code for eSIM installation
activationCode
string
Manual activation code (LPA string)
smdpAddress
string
SM-DP+ server address
matchingId
string
Matching ID for eSIM activation
esimStatus
string
Current status of the eSIM
data
string
Data allowance (e.g., “5GB”, “Unlimited”)
totalVolume
number
Total data volume in bytes
orderUsage
number
Data consumed in bytes
data_usage_remain
number
Remaining data in bytes
validity
number
Validity period in days
activateTime
string
Activation timestamp (ISO 8601)
expiredTime
string
Expiry timestamp (ISO 8601)
packageDetails
object
Additional package information including coverage and network providers

Example Request

curl -X GET 'https://api.vellosim.com/api/esim/esim_64f8a1b2c3d4e5f6a7b8c9d0' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "_id": "esim_64f8a1b2c3d4e5f6a7b8c9d0",
  "packageCode": "US_5GB_30D",
  "packageName": "USA 5GB - 30 Days",
  "orderNo": "ORD-2024-001234",
  "transactionId": "esim_1699564800_12345",
  "esimTranNo": "ESIM-TXN-567890",
  "iccid": "8944500123456789012",
  "imsi": "310260123456789",
  "msisdn": null,
  "ac": "ABC-123-DEF-456",
  "qrCodeUrl": "https://vellosim.com/qr/abc123",
  "shortUrl": "https://vls.to/abc123",
  "activationCode": "LPA:1$smdp.gsma.com$ABC-123-DEF-456",
  "smdpAddress": "smdp.gsma.com",
  "matchingId": "ABC-123-DEF-456",
  "eid": "89049032123456789012345678901234",
  "smdpStatus": "INSTALLED",
  "activeType": "AUTOMATIC",
  "activateTime": "2024-10-15T10:30:00Z",
  "expiredTime": "2024-11-14T10:30:00Z",
  "esimStatus": "ACTIVE",
  "data": "5GB",
  "totalVolume": 5368709120,
  "orderUsage": 1073741824,
  "data_usage_remain": 4294967296,
  "validity": 30,
  "durationUnit": "DAY",
  "totalDuration": 30,
  "validity_usage_remain": 25,
  "pin": null,
  "puk": null,
  "apn": "internet",
  "smsStatus": 0,
  "dataType": 1,
  "price": 8000,
  "currency": "NGN",
  "packageDetails": {
    "coverage": ["United States"],
    "networkProviders": ["AT&T", "T-Mobile", "Verizon"],
    "dataType": "Data Only",
    "speed": "4G/5G"
  },
  "isActive": true,
  "createdAt": "2024-10-15T10:00:00Z",
  "updatedAt": "2024-11-05T08:15:00Z"
}

Use Cases

Show the QR code for eSIM installation:
async function displayQRCode(esimId) {
  const esim = await getEsimDetails(esimId);
  
  // Display QR code image
  document.getElementById('qr-code').src = esim.qrCodeUrl;
  
  // Show manual activation code
  document.getElementById('activation-code').textContent = esim.activationCode;
  
  // Show installation instructions
  console.log('Scan this QR code to install your eSIM');
  console.log('Or manually enter:', esim.activationCode);
}
Track data consumption:
async function checkDataUsage(esimId) {
  const esim = await getEsimDetails(esimId);
  
  const totalGB = esim.totalVolume / (1024 ** 3);
  const usedGB = esim.orderUsage / (1024 ** 3);
  const remainingGB = esim.data_usage_remain / (1024 ** 3);
  
  const usagePercentage = (usedGB / totalGB) * 100;
  
  console.log(`Data Usage: ${usedGB.toFixed(2)}GB / ${totalGB.toFixed(2)}GB`);
  console.log(`Remaining: ${remainingGB.toFixed(2)}GB (${(100 - usagePercentage).toFixed(1)}%)`);
  
  // Alert if running low
  if (usagePercentage > 80) {
    console.warn('⚠️ Data usage is above 80%. Consider topping up.');
  }
  
  return { totalGB, usedGB, remainingGB, usagePercentage };
}
Monitor validity period:
async function checkExpiry(esimId) {
  const esim = await getEsimDetails(esimId);
  
  const now = new Date();
  const expiryDate = new Date(esim.expiredTime);
  const daysRemaining = Math.ceil((expiryDate - now) / (1000 * 60 * 60 * 24));
  
  if (daysRemaining <= 0) {
    console.log('❌ eSIM has expired');
  } else if (daysRemaining <= 3) {
    console.warn(`⚠️ eSIM expires in ${daysRemaining} days`);
  } else {
    console.log(`✅ eSIM expires in ${daysRemaining} days`);
  }
  
  return daysRemaining;
}
Generate shareable installation information:
async function shareEsimDetails(esimId) {
  const esim = await getEsimDetails(esimId);
  
  const installInfo = {
    name: esim.packageName,
    qrCode: esim.qrCodeUrl,
    shortUrl: esim.shortUrl,
    manualCode: esim.activationCode,
    smdpAddress: esim.smdpAddress,
    matchingId: esim.matchingId,
    apn: esim.apn,
    validity: `${esim.validity} days`,
    data: esim.data
  };
  
  // Share via email, SMS, or download as PDF
  return installInfo;
}

Installation Instructions

Generate installation instructions for end users:
async function getInstallInstructions(esimId) {
  const esim = await getEsimDetails(esimId);
  
  return {
    ios: [
      'Open Settings on your iPhone',
      'Tap Cellular or Mobile Data',
      'Tap Add eSIM',
      'Scan the QR code or enter details manually',
      `SM-DP+ Address: ${esim.smdpAddress}`,
      `Activation Code: ${esim.matchingId}`
    ],
    android: [
      'Open Settings on your Android device',
      'Go to Network & Internet > Mobile Network',
      'Tap the + icon to add a carrier',
      'Select "Download a SIM instead?"',
      'Scan the QR code or enter details manually',
      `SM-DP+ Address: ${esim.smdpAddress}`,
      `Activation Code: ${esim.matchingId}`
    ],
    qrCode: esim.qrCodeUrl,
    manualSetup: {
      smdpAddress: esim.smdpAddress,
      matchingId: esim.matchingId,
      activationCode: esim.activationCode
    }
  };
}

Next Steps