Skip to main content
GET
/
api
/
esim
/
:esimId
Get eSIM Details
curl --request GET \
  --url https://api.vellosim.com/api/esim/:esimId \
  --header 'X-API-Key: <api-key>'
{
  "_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"
}

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.

​
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

Get All eSIMs

View all your eSIM orders

Top-Up eSIM

Add more data to this eSIM

Usage Monitoring

Set up data usage alerts

Installation Guide

Help users install eSIMs