Get eSIM details

POST

/esims/details

const url = 'https://api.roamex.com/v1/esims/details?lang=nl';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"esimId":"00000000-0000-4000-8000-0000000000c1"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url 'https://api.roamex.com/v1/esims/details?lang=nl' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "esimId": "00000000-0000-4000-8000-0000000000c1" }'

Returns one eSIM with its install data, its status page link and what you can do with it next. canCancel is judged on the stored record as of lastRefreshedAt; /esims/cancel checks the eSIM live and may still refuse.

Authorizations

apiKey

Parameters

Query Parameters

lang

string

default: en

Language of plan and destination names in the response: en, nl, es, de, it, fr, pl, pt, tr, el, cs or ro. Any other value, or none, gives English. It never changes which items are returned or any figure.

Example

nl

Request Body^required

application/json

object

esimId

required

An eSIM id from /esims/purchase or /esims/list.

string format: uuid

Example

{
  "esimId": "00000000-0000-4000-8000-0000000000c1"
}

Responses

200

The eSIM.

application/json

object

success

required

boolean

esim

required

object

required

string format: uuid

plan

required

object

name

required

string

region

required

object

code

required

string | null

name

required

string

isRegional

required

boolean

countries

Regional eSIMs only.

Array<object>

object

code

required

string

name

required

string

status

required

pending: not ready to install yet.
ready: can be installed, including after it was removed from a device.
installed: on a device.
active: in use, and data has been used.
expired: all data is used (statusLabel Used Up). An eSIM past its end date keeps its other status; compare validity.expiresAt.
cancelled: cancelled by you or on the network, or spent and removed from the device.

string

Allowed values: pending ready installed active expired cancelled

statusLabel

required

string

Allowed values: Pending Ready Installed Active Used Up Cancelled

canCancel

required

Whether /esims/cancel would accept this eSIM, judged on the stored record as of lastRefreshedAt. The cancel itself checks live and may still refuse.

boolean

canTopUp

required

Whether the eSIM can take a top-up: it is provisioned, not cancelled, not past its end date, below the top-up limit, and its destination is still sold.

boolean

data

required

object

total

required

object

bytes

required

0 when unknown.

integer

formatted

required

Two decimals in GB, whole numbers in MB and KB, 0 B when unknown.

string

used

required

object

bytes

required

0 when unknown.

integer

formatted

required

Two decimals in GB, whole numbers in MB and KB, 0 B when unknown.

string

remaining

required

object

bytes

required

0 when unknown.

integer

formatted

required

Two decimals in GB, whole numbers in MB and KB, 0 B when unknown.

string

percentUsed

required

Rounded. 0 when the total is unknown.

integer

validity

required

object

days

required

integer | null

unit

required

string

expiresAt

required

When the validity ends, once known.

string | null

activatedAt

required

When the eSIM was activated, once known.

string | null

installation

required

object

qrCodeUrl

required

A QR code image to install the eSIM. null until it is ready, and once it is cancelled or expired.

string | null format: uri

activationCode

required

The install code. Kept after the eSIM is cancelled, as a record.

string | null

installUrls

required

One-tap install links. null when there is no activation code, and once the eSIM is cancelled or expired.

object

ios

required

string format: uri

android

required

string format: uri

statusPageUrl

required

The traveller’s status page for this eSIM. On your shop’s subdomain while your shop is live, otherwise on roamex.com.

string format: uri

fulfillment

required

null until the eSIM has been emailed to a traveller.

object

fulfilledAt

required

When it was first sent.

string

email

required

The most recent recipient.

string | null

name

required

string | null

costCentre

required

The costCentre sent with the purchase. Never shown to the traveller.

string | null

createdAt

required

string format: date-time

lastRefreshedAt

required

When the eSIM’s figures were last read from the network.

string | null

Example

{
  "success": true,
  "esim": {
    "id": "00000000-0000-4000-8000-0000000000c1",
    "plan": {
      "name": "Japan · 1 GB · 7 days"
    },
    "region": {
      "code": "JP",
      "name": "Japan",
      "isRegional": false
    },
    "status": "ready",
    "statusLabel": "Ready",
    "canCancel": true,
    "canTopUp": true,
    "data": {
      "total": {
        "bytes": 1073741824,
        "formatted": "1.00 GB"
      },
      "used": {
        "bytes": 0,
        "formatted": "0 B"
      },
      "remaining": {
        "bytes": 1073741824,
        "formatted": "1.00 GB"
      },
      "percentUsed": 0
    },
    "validity": {
      "days": 7,
      "unit": "DAY",
      "expiresAt": null,
      "activatedAt": null
    },
    "installation": {
      "qrCodeUrl": "https://roamex.com/q/example-status-token",
      "activationCode": "LPA:1$smdp.example.com$EXAMPLE-MATCHING-ID",
      "installUrls": {
        "ios": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA%3A1%24smdp.example.com%24EXAMPLE-MATCHING-ID",
        "android": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA%3A1%24smdp.example.com%24EXAMPLE-MATCHING-ID"
      }
    },
    "statusPageUrl": "https://roamex.com/esim/example-status-token",
    "fulfillment": null,
    "costCentre": null,
    "createdAt": "2026-10-21T14:58:00+00:00",
    "lastRefreshedAt": "2026-10-21T15:05:00+00:00"
  }
}

Headers

X-RateLimit-Limit

integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining

integer

Calls left in the current minute.

X-RateLimit-Reset

integer

When the current window ends, in Unix seconds.

400

INVALID_JSON: the body is missing or not a JSON object.
MISSING_ESIM_ID: esimId is missing.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

401

AUTH_ERROR: the key is missing, malformed, unknown or revoked. The message says which, for example Missing Authorization header, Invalid Authorization header format. Use: Bearer <api_key>, Invalid API key format or Invalid API key.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid API key"
  }
}

403

AUTH_ERROR: the account is suspended (Your account is suspended. Please contact support.) or rejected (Account is not approved for API access).

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

404

ESIM_NOT_FOUND: no eSIM with this id belongs to your account.
NOT_FOUND: the API is switched off on the platform.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

413

PAYLOAD_TOO_LARGE: the Content-Length header is over 100 KB.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

429

RATE_LIMITED: the account’s per-minute budget for this endpoint group is used up, or too many refused keys came from this IP address. Wait the Retry-After seconds.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please wait 42 seconds before retrying."
  }
}

Headers

X-RateLimit-Limit

integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining

integer

Calls left in the current minute.

X-RateLimit-Reset

integer

When the current window ends, in Unix seconds.

Retry-After

integer

Seconds to wait before retrying.

500

INTERNAL_ERROR: an unexpected error on our side.
AUTH_ERROR with status 500: the key could not be checked because of an error on our side. Retry with backoff.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

Get eSIM details

Authorizations

Parameters

Query Parameters

Example

Request Bodyrequired

Example

Responses

200

Example

Headers

400

Example

401

Example

403

Example

404

Example

413

Example

429

Example

Headers

500

Example

Request Body^required