Skip to Content
OpenRoam Docs
eSIMs

Get eSIM usage

Returns the current data, SMS and voice usage of an eSIM.

GET
/v1/esims/{iccid}/usage

Returns the current data, SMS and voice usage of an eSIM.

Reads the live usage when the request is made and returns esimStatus, profileStatus and the allowed and remaining data (MB), SMS (messages) and voice (minutes), including top-ups. An amount is null when it is unlimited (isDataUnlimited, isSmsUnlimited, isVoiceUnlimited), not reported or not included. When the usage cannot be read live, or the plan does not report live usage, it returns the last known usage. An ICCID that is not one of your eSIMs gives 404 / 10004.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Path Parameters

iccid*string

The eSIM's ICCID, from the order item's fulfillment.result.details.iccid.

Response Body

OK

  1. response

An eSIM's statuses and its current allowances and remaining amounts, plan and top-ups together: data in MB (1 MB = 1024 KB), SMS in messages, voice in minutes. An amount is null when it is unlimited (its is...Unlimited flag is then true), not reported or not included.

iccid*string

The eSIM's ICCID.

esimStatus*string

The eSIM's lifecycle status, as the order item's esimStatus.

Value in"new""procuring""pending""failed""ready""cancelled""revoked""expired""unknown"
profileStatus*string

The installed profile's status, as the order item's profileStatus.

Value in"empty""new""downloaded""installed""activated""inactive""deleted""revoked""expired""unknown"
start?|

When the plan started, in UTC; null until it is activated.

Formatdate-time
end?|

When the plan ends, in UTC, as last reported; null while no end is reported.

Formatdate-time
allowedData?|

Total data in MB; null when unlimited or not reported.

Formatint64
remainingData?|

Remaining data in MB; null when unlimited or not reported.

Formatint64
isDataUnlimited*boolean

Whether the data is unlimited.

allowedSms?|

Total SMS, in messages; null when unlimited, not reported or not included.

Formatint64
remainingSms?|

Remaining SMS, in messages; null when unlimited, not reported or not included.

Formatint64
isSmsUnlimited*boolean

Whether SMS are unlimited.

allowedVoice?|

Total voice, in minutes; null when unlimited, not reported or not included.

Formatint64
remainingVoice?|

Remaining voice, in whole minutes; null when unlimited, not reported or not included.

Formatint64
isVoiceUnlimited*boolean

Whether voice is unlimited.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/esims/8944501234567890123/usage'
Example Response
{  "iccid": "string",  "esimStatus": "new",  "profileStatus": "empty",  "start": "2019-08-24T14:15:22Z",  "end": "2019-08-24T14:15:22Z",  "allowedData": 0,  "remainingData": 0,  "isDataUnlimited": true,  "allowedSms": 0,  "remainingSms": 0,  "isSmsUnlimited": true,  "allowedVoice": 0,  "remainingVoice": 0,  "isVoiceUnlimited": true}