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

Name	Type	Required	Description	Example
`orderNo`	String	Optional	Platform order number	`ORD20240101123456`
`iccid`	String	Optional	eSIM ICCID	`8901234567890123456`
`startTime`	String	Optional	Query start time (UTC)	`2024-01-01 00:00:00`
`endTime`	String	Optional	Query end time (UTC)	`2024-01-31 23:59:59`
`pageSize`	Integer	Optional	Results per page (max 100)	`20`
`pageNo`	Integer	Optional	Page number	`1`

At least one filter parameter is required: orderNo, iccid, or time period (startTime + endTime).

Example Request - Query by Order Number

curl --location --request POST 'https://your-api-domain.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://your-api-domain.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

curl --location --request POST 'https://your-api-domain.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-01 00:00:00",
    "endTime": "2024-01-31 23:59:59",
    "pageSize": 50,
    "pageNo": 1
}'

Response Parameters

Name	Type	Description
`success`	Boolean	`true` = succeeded, `false` = failed
`errorCode`	String	Error code when failed
`errorMsg`	String	Error message
`obj.esimList`	Array	List of eSIM profiles
`obj.total`	Integer	Total number of results
`obj.pageNo`	Integer	Current page number
`obj.pageSize`	Integer	Results per page

eSIM Object

Field	Type	Description	Example
`orderNo`	String	Order number	`ORD20240101123456`
`iccid`	String	eSIM ICCID	`8901234567890123456`
`esimTranNo`	String	eSIM transaction number	`ESIM123456`
`packageCode`	String	Package code	`TH_1_7`
`packageName`	String	Package name	`Thailand 1GB 7 Days`
`smdpAddress`	String	SM-DP+ server address	`smdp.example.com`
`matchId`	String	Activation code	`XXXX-XXXX-XXXX-XXXX`
`profileStatus`	String	Current status	`ACTIVATED`
`usedVolume`	Long	Used data in bytes	`524288000`
`totalVolume`	Long	Total data in bytes	`1073741824`
`expiredTime`	String	Expiry date (UTC)	`2024-02-07 00:00:00`
`createTime`	String	Order creation time	`2024-01-01 12:00:00`
`qrCode`	String	Base64 QR code image	`data:image/png;base64,...`
`appleInstallUrl`	String	Apple direct install URL	`https://esimsetup.apple.com/...`

Example Success Response

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": {
        "esimList": [
            {
                "orderNo": "ORD20240101123456",
                "iccid": "8901234567890123456",
                "esimTranNo": "ESIM123456",
                "packageCode": "TH_1_7",
                "packageName": "Thailand 1GB 7 Days",
                "smdpAddress": "smdp.example.com",
                "matchId": "XXXX-XXXX-XXXX-XXXX",
                "profileStatus": "ACTIVATED",
                "usedVolume": 524288000,
                "totalVolume": 1073741824,
                "expiredTime": "2024-02-07 00:00:00",
                "createTime": "2024-01-01 12:00:00",
                "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
                "appleInstallUrl": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=..."
            }
        ],
        "total": 1,
        "pageNo": 1,
        "pageSize": 20
    }
}

Profile Status Values

Status	Description
`GOT_RESOURCE`	Profile allocated, ready for download
`ACTIVATED`	Profile downloaded and activated
`IN_USE`	Profile is actively being used
`USED_UP`	Data exhausted
`EXPIRED`	Profile validity expired
`CANCELLED`	Profile cancelled
`SUSPENDED`	Profile temporarily suspended
`REVOKED`	Profile permanently revoked

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 usedVolume = 524288000;  // 500 MB
const totalVolume = 1073741824; // 1 GB
const remainingPercent = ((totalVolume - usedVolume) / totalVolume * 100).toFixed(1);
// Result: 51.2%

Pagination

For large result sets, use pagination:

# Get first page
curl --location --request POST 'https://your-api-domain.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-01 00:00:00",
    "endTime": "2024-12-31 23:59:59",
    "pageSize": 100,
    "pageNo": 1
}'
 
# Get second page
curl --location --request POST 'https://your-api-domain.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-01 00:00:00",
    "endTime": "2024-12-31 23:59:59",
    "pageSize": 100,
    "pageNo": 2
}'

Order Profiles Profile Management