Skip to Content
OpenRoam Docs
eSIMs

Provision a deferred eSIM

Provisions a deferred eSIM bought with `inputs.isInstant: false` and returns it.

POST
/v1/esims/{id}/provisioning

Provisions a deferred eSIM bought with inputs.isInstant: false and returns it.

Creates the eSIM for an order item that delivered an entitlement, and returns it as GET /esims/{iccid} does. The item's result moves to provisioning.status processing and then ready, and each change sends an order.fulfillment.updated webhook. An Idempotency-Key header with a UUID is required: a retry with the same key and body after the call finished returns the eSIM as it reads now and starts nothing again, 409 / 12002 with Retry-After while the call is still running, and a changed body gives 409 / 12001. The optional body { travelStartDate } is needed when the plan requires the first day of travel and the order did not send it (400 / 10001 without it); a date other than the one recorded, or a new date once provisioning has started, gives 409 / 10005. An instant eSIM gives 400 / 10001, and an ID that names no eSIM purchase of yours, such as a top-up item, gives 404 / 10004.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Path Parameters

id*string

The order item ID of the deferred eSIM purchase.

Formatuuid

Header Parameters

Idempotency-Key*string

UUID idempotency key for safe retries of this operation.

Formatuuid

Request Body

Optional: { travelStartDate }, the first day of travel.

  1. body

The optional body of POST /esims/{id}/provisioning.

travelStartDate?|

The first day of travel, for a plan that requires it when the order did not send it. When the order recorded a date, it must be the same date.

Formatdate

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 POST 'https://api.sandbox.openroam.com/v1/esims/01a1432e-7121-7b0e-a0a0-c35454d3b883/provisioning' \  -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \  -H 'Content-Type: application/json' \  -d '{}'
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"}