Skip to Content
OpenRoam Docs
eSIMs

Get an eSIM

Returns one of your eSIMs by its ICCID, with its installation details, plan and top-ups.

GET
/v1/esims/{iccid}/profile

Returns one of your eSIMs by its ICCID, with its installation details, plan and top-ups.

Returns the eSIM as last recorded, without a live refresh: esimStatus and profileStatus as the order item names them, the SIM details (LPA code, QR code URL and quick-install links), the plan, its data (MB), SMS (messages) and voice (minutes) allowances, any top-ups, and expiresAt, null until the eSIM is activated. 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

One of your eSIMs: its order, statuses, plan, installation details, allowances and top-ups.

orderId*string

The order that bought the eSIM.

Formatuuid
orderItemId*string

The order item that bought the eSIM, which POST /esims/{id}/provisioning takes.

Formatuuid
iccid?|

The eSIM's ICCID; null until the eSIM is provisioned.

packageName*string

Display name of the purchased plan.

countryImage?|

Image URL of the destination, or null.

esimStatus*string

The eSIM's lifecycle status, as the order item's esimStatus. An eSIM under review reads as pending.

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

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

Value in"empty""new""downloaded""installed""activated""inactive""deleted""revoked""expired""unknown"
day*integer

How many days the plan is valid, counted from activation.

Formatint32
isApnAutomatic*boolean

Whether the device sets the APN automatically; otherwise use apn.

withSMS*boolean

Whether the plan includes SMS.

withCall*boolean

Whether the plan includes calls.

properties?|

Plan features, such as hotspot and top-up support.

esim?|

SIM details: LPA code, QR code URL, quick-install links and usage; null until the eSIM is provisioned.

addon*array<>

The top-ups applied to the eSIM.

data?|

The plan's data allowance, as the offer shows it.

sms?|

The plan's SMS allowance; null when the plan includes no SMS.

voice?|

The plan's calling allowance; null when the plan includes no calls.

apn?|

APN settings for manual device setup.

expiresAt?|

When the plan ends, in UTC, as reported once the plan has started: its activation plus day, extended by top-ups. Null until the eSIM is activated.

Formatdate-time
Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/esims/8944501234567890123/profile'
Example Response
{  "orderId": "b3e1eced-f2bd-4d8c-9765-fbc9d1d222d5",  "orderItemId": "33207bce-c741-4896-a76b-8afcf6e4179a",  "iccid": "string",  "packageName": "string",  "countryImage": "string",  "esimStatus": "new",  "profileStatus": "empty",  "day": 0,  "isApnAutomatic": true,  "withSMS": true,  "withCall": true,  "properties": {    "withKyc": true,    "withTopUp": true,    "withHotspot": true,    "withDataRoaming": true,    "withSubscription": true,    "withDestinationInstall": true,    "withUsageCheck": true,    "technology": "string",    "activation": "string",    "charge": "string"  },  "esim": {    "iccid": "string",    "lpaCode": "string",    "smdpAddress": "string",    "activationCode": "string",    "qrCodeUrl": "string",    "pin": "string",    "puk": "string",    "number": "string",    "iosQuickInstall": "string",    "androidQuickInstall": "string",    "usage": {      "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    }  },  "addon": [    {      "packageName": "string",      "usage": {        "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      }    }  ],  "data": {    "amount": 0,    "unit": "string",    "isUnlimited": true,    "label": "string"  },  "sms": {    "amount": 0,    "unit": "string",    "isUnlimited": true,    "label": "string",    "type": "string"  },  "voice": {    "amount": 0,    "unit": "string",    "isUnlimited": true,    "label": "string",    "type": "string"  },  "apn": {    "apn": "string",    "apnUsername": "string",    "apnPassword": "string"  },  "expiresAt": "2019-08-24T14:15:22Z"}