eSIM Platform
Docs
Query Profiles

Query Profiles

Query allocated eSIM profiles and order status

Query Profiles

Query the status of your allocated eSIM profiles and orders.

Query All Allocated Profiles

Endpoint: POST /api/v1/open/esim/query

Request Parameters

NameTypeRequiredDescriptionExample
orderNoStringOptionalPlatform order numberORD20240101123456
iccidStringOptionaleSIM ICCID8901234567890123456
esimTranNoStringOptionaleSIM transaction numberESIM123456789
startTimeStringOptionalQuery start time (ISO 8601)2024-01-01T00:00:00+0000
endTimeStringOptionalQuery end time (ISO 8601)2024-01-31T23:59:59+0000
pager.pageNumIntegerOptionalPage number (default: 1)1
pager.pageSizeIntegerOptionalResults per page (max 100, default: 20)20

Example Request - Query by Order Number

curl --location --request POST 'https://b2b.hiroaming.com/api/v1/open/esim/query' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "orderNo": "ORD20240101123456"
}'

Example Request - Query by ICCID

curl --location --request POST 'https://b2b.hiroaming.com/api/v1/open/esim/query' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "iccid": "8901234567890123456"
}'

Example Request - Query by Time Period with Pagination

curl --location --request POST 'https://b2b.hiroaming.com/api/v1/open/esim/query' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "startTime": "2024-01-01T00:00:00+0000",
    "endTime": "2024-01-31T23:59:59+0000",
    "pager": {
        "pageNum": 1,
        "pageSize": 50
    }
}'

Response Parameters

NameTypeDescription
successBooleantrue = succeeded, false = failed
errorCodeStringError code when failed
errorMsgStringError message
obj.esimListArrayList of eSIM profiles
obj.pager.totalIntegerTotal number of results
obj.pager.pageNumIntegerCurrent page number
obj.pager.pageSizeIntegerResults per page

eSIM Object

FieldTypeDescriptionExample
esimTranNoStringeSIM transaction numberESIM123456789
orderNoStringPlatform order numberORD20240101123456
transactionIdStringVendor transaction IDTX123456
iccidStringeSIM ICCID8901234567890123456
imsiStringIMSI number123456789012345
msisdnStringPhone number (if applicable)+66812345678
eidStringeUICC ID89049032000000000000000000012345
acStringActivation codeLPA:1$smdp.example.com$XXXX
qrCodeUrlStringQR code image URLhttps://...
shortUrlStringShort installation URLhttps://...
smdpStatusStringSM-DP+ statusRELEASED, INSTALLED, ENABLED
esimStatusStringeSIM statusGOT_RESOURCE, IN_USE, USED_UP
smsStatusIntegerSMS support status0, 1, 2
activeTypeIntegerActivation type1 = First Installation, 2 = First Network
dataTypeIntegerData plan type1 = Fixed, 2 = Day Pass
totalVolumeLongTotal data in bytes1073741824
totalDurationIntegerPlan duration7
durationUnitStringDuration unitDAY
orderUsageLongUsed data in bytes524288000
activateTimeStringActivation timestamp2024-01-02T10:30:00+0000
expiredTimeStringExpiry timestamp2024-02-07T00:00:00+0000
installationTimeStringInstallation timestamp2024-01-01T15:00:00+0000
pinStringeSIM PIN code1234
pukStringeSIM PUK code12345678
apnStringAccess Point Nameinternet
ipExportStringIP exit country codeTH
supportTopUpTypeIntegerTop-up support type0, 1, 2
fupPolicyStringFair Usage Policy384 Kbps after limit
packageListArrayList of packages on this eSIMSee Package Object

SMS Status Values

ValueDescription
0SMS not supported
1SMS supported (API + Mobile)
2SMS supported (API only)

Active Type Values

ValueDescription
1Activates on first installation
2Activates on first network connection

Data Type Values

ValueDescription
1Data in Total (fixed data amount)
2Daily Limit - Speed Reduced after limit
3Daily Limit - Cut-off after limit
4Daily Unlimited

Support TopUp Type Values

ValueDescription
0Top-up not supported
1Top-up supported (same slug only)
2Top-up supported (any compatible package)

SM-DP+ Status Values

StatusDescription
RELEASEDProfile ready for download
DOWNLOADEDProfile downloaded to device
INSTALLEDProfile installed on device
ENABLEDProfile enabled and active
DISABLEDProfile disabled
DELETEDProfile deleted from device

eSIM Status Values

StatusDescription
GOT_RESOURCEProfile allocated, ready for download
IN_USEProfile is actively being used
USED_UPData exhausted
EXPIREDProfile validity expired
CANCELLEDProfile cancelled
SUSPENDEDProfile temporarily suspended
REVOKEDProfile permanently revoked

Example Success Response

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": {
        "esimList": [
            {
                "esimTranNo": "ESIM123456789",
                "orderNo": "ORD20240101123456",
                "transactionId": "TX123456",
                "iccid": "8901234567890123456",
                "imsi": "123456789012345",
                "msisdn": "",
                "eid": "",
                "ac": "LPA:1$smdp.example.com$XXXX-XXXX-XXXX-XXXX",
                "qrCodeUrl": "https://static.example.com/qr/xxx.png",
                "shortUrl": "https://esim.example.com/i/xxx",
                "smdpStatus": "RELEASED",
                "esimStatus": "GOT_RESOURCE",
                "smsStatus": 2,
                "activeType": 1,
                "dataType": 1,
                "totalVolume": 1073741824,
                "totalDuration": 7,
                "durationUnit": "DAY",
                "orderUsage": 0,
                "activateTime": null,
                "expiredTime": null,
                "installationTime": null,
                "pin": "",
                "puk": "",
                "apn": "internet",
                "ipExport": "TH",
                "supportTopUpType": 2,
                "fupPolicy": "",
                "packageList": [
                    {
                        "packageCode": "TH_1_7",
                        "slug": "TH_1_7",
                        "volume": 1073741824,
                        "duration": 7,
                        "locationCode": "TH"
                    }
                ]
            }
        ],
        "pager": {
            "pageSize": 20,
            "pageNum": 1,
            "total": 1
        }
    }
}

Calculating Data Usage

Data values are in bytes. To convert:

// Convert bytes to human readable
function formatBytes(bytes) {
    if (bytes === 0) return '0 B';
    const k = 1024;
    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
    const i = Math.floor(Math.log(bytes) / Math.log(k));
    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
}
 
// Calculate remaining data percentage
const orderUsage = 524288000;  // 500 MB used
const totalVolume = 1073741824; // 1 GB total
const remainingPercent = ((totalVolume - orderUsage) / totalVolume * 100).toFixed(1);
// Result: 51.2%

Pagination

For large result sets, use the pager object:

# Get first page
curl --location --request POST 'https://b2b.hiroaming.com/api/v1/open/esim/query' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "startTime": "2024-01-01T00:00:00+0000",
    "endTime": "2024-12-31T23:59:59+0000",
    "pager": {
        "pageNum": 1,
        "pageSize": 100
    }
}'
 
# Get second page
curl --location --request POST 'https://b2b.hiroaming.com/api/v1/open/esim/query' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "startTime": "2024-01-01T00:00:00+0000",
    "endTime": "2024-12-31T23:59:59+0000",
    "pager": {
        "pageNum": 2,
        "pageSize": 100
    }
}'
Order ProfilesProfile Management
Query Profiles - eSIM Platform