Get eSIM Details
curl --request GET \
--url https://api.vellosim.com/api/esim/:esimId \
--header 'X-API-Key: <api-key>'const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.vellosim.com/api/esim/:esimId', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.vellosim.com/api/esim/:esimId"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vellosim.com/api/esim/:esimId",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.vellosim.com/api/esim/:esimId"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"_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"
}
{
"success": false,
"message": "Forbidden",
"error": {
"code": "NOT_YOUR_ESIM",
"details": "This eSIM does not belong to your account"
}
}
{
"success": false,
"message": "Not Found",
"error": {
"code": "ESIM_NOT_FOUND",
"details": "eSIM with the specified ID does not exist"
}
}
Orders
Get eSIM Details
Get detailed information for a specific eSIM order
GET
/
api
/
esim
/
:esimId
Get eSIM Details
curl --request GET \
--url https://api.vellosim.com/api/esim/:esimId \
--header 'X-API-Key: <api-key>'const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.vellosim.com/api/esim/:esimId', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.vellosim.com/api/esim/:esimId"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vellosim.com/api/esim/:esimId",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.vellosim.com/api/esim/:esimId"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"_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"
}
{
"success": false,
"message": "Forbidden",
"error": {
"code": "NOT_YOUR_ESIM",
"details": "This eSIM does not belong to your account"
}
}
{
"success": false,
"message": "Not Found",
"error": {
"code": "ESIM_NOT_FOUND",
"details": "eSIM with the specified ID does not exist"
}
}
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
string
required
API Key for authentication
YOUR_API_KEY
Path Parameters
string
required
The unique identifier of the eSIM order
Response
string
eSIM unique identifier
string
Package code of the purchased eSIM
string
Display name of the package
string
Transaction ID for the purchase
string
ICCID (Integrated Circuit Card Identifier)
string
IMSI (International Mobile Subscriber Identity)
string
Phone number assigned to the eSIM (if applicable)
string
URL to the QR code for eSIM installation
string
Manual activation code (LPA string)
string
SM-DP+ server address
string
Matching ID for eSIM activation
string
Current status of the eSIM
string
Data allowance (e.g., “5GB”, “Unlimited”)
number
Total data volume in bytes
number
Data consumed in bytes
number
Remaining data in bytes
number
Validity period in days
string
Activation timestamp (ISO 8601)
string
Expiry timestamp (ISO 8601)
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"
async function getEsimDetails(esimId) {
const response = await fetch(
`https://api.vellosim.com/api/esim/${esimId}`,
{
method: 'GET',
headers: {
'X-API-Key': ' YOUR_API_KEY',
'Content-Type': 'application/json'
}
}
);
const esim = await response.json();
console.log('eSIM Details:');
console.log('ICCID:', esim.iccid);
console.log('Status:', esim.esimStatus);
console.log('Data Remaining:', formatBytes(esim.data_usage_remain));
console.log('Expires:', new Date(esim.expiredTime).toLocaleDateString());
return esim;
}
// Usage
const esim = await getEsimDetails('esim_64f8a1b2c3d4e5f6a7b8c9d0');
import requests
from datetime import datetime
def get_esim_details(esim_id):
"""Get detailed information for a specific eSIM"""
headers = {
'X-API-Key': ' YOUR_API_KEY',
'Content-Type': 'application/json'
}
response = requests.get(
f'https://api.vellosim.com/api/esim/{esim_id}',
headers=headers
)
return response.json()
# Usage
esim = get_esim_details('esim_64f8a1b2c3d4e5f6a7b8c9d0')
print(f"Package: {esim['packageName']}")
print(f"ICCID: {esim['iccid']}")
print(f"Status: {esim['esimStatus']}")
print(f"Data Remaining: {esim['data_usage_remain'] / (1024**3):.2f} GB")
print(f"Expires: {datetime.fromisoformat(esim['expiredTime']).strftime('%Y-%m-%d')}")
<?php
function getEsimDetails($esimId) {
$apiKey = 'YOUR_API_KEY';
$ch = curl_init("https://api.vellosim.com/api/esim/{$esimId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-API-Key: ' . $apiKey,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$esim = json_decode($response, true);
curl_close($ch);
return $esim;
}
// Usage
$esim = getEsimDetails('esim_64f8a1b2c3d4e5f6a7b8c9d0');
echo "Package: " . $esim['packageName'] . "\n";
echo "ICCID: " . $esim['iccid'] . "\n";
echo "Status: " . $esim['esimStatus'] . "\n";
echo "QR Code: " . $esim['qrCodeUrl'] . "\n";
?>
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"
}
{
"success": false,
"message": "Forbidden",
"error": {
"code": "NOT_YOUR_ESIM",
"details": "This eSIM does not belong to your account"
}
}
{
"success": false,
"message": "Not Found",
"error": {
"code": "ESIM_NOT_FOUND",
"details": "eSIM with the specified ID does not exist"
}
}
Use Cases
Display QR Code
Display QR Code
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);
}
Monitor Data Usage
Monitor Data Usage
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 };
}
Check Expiry
Check Expiry
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;
}
Share Installation Details
Share Installation Details
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
⌘I
