API v2.5 / eSIMs / Get eSIM details

Server

GET

/esims/{iccid}

eSIMGo API

This endpoint allows you to retrieve detailed information about a specific eSIM using its ICCID (Integrated Circuit Card Identifier).

eSIM profile statuses:

Released - The eSIM is not installed. If there is a firstInstalledDateTime then the eSIM has been installed previously and then uninstalled again.

Installed - The eSIM is installed.

Downloaded - This is unlikely to be seen very often. It would be when the bundle has been delivered to LPA, but the eSIM has not yet been released.

Unavailable - An eSIM in this status cannot be installed. We recommend reissuing a new eSIM instead, especially if the eSIM is not already installed.

Deactivated - The eSIM has been deactivated and can no longer be used.

lastDevice shows the device the eSIM was last downloaded to or installed on, when known. Only the device fields with a known value are returned. To be told when profileStatus changes instead of polling this endpoint, use the Profile Status Change notification.

Authorizations

apiKeyAuth

Parameters

Path Parameters

iccid

required

string

(Required) The ICCID of the eSIM

Example

8944123456789012000

Query Parameters

additionalFields

string

Example

installUrl

Responses

200

object

iccid

The Integrated Circuit Card Identifier of the SIM card

string

894123456789123456

msisdn

The phone number. Assign only to eSIMs with SMS or voice allowances

string

4471234131234

pin

The Personal Identification Number for the SIM card

string

puk

The Personal Unblocking Key for the SIM card

string

123445678

matchingId

A unique identifier for matching purposes (used for eSIM activation)

string

JQ-123456-ABCDEPFX

smdpAddress

The Subscription Manager Data Preparation server address (used for eSIM activation)

string

http://rsp.example.com

profileStatus

The current status of the SIM profile

string

Installed

physical

True for a physical SIM (pSIM), false for an eSIM

boolean

firstInstalledDateTime

The timestamp of when the profile was first installed (in milliseconds since epoch)

integer format: int64

1723541877280

customerRef

Customer reference information

string

appleInstallUrl

URL used for eSIM installation for Apple devices with iOS 17.4 and above

string

https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$rsp-1234.example.com$ABCD-ABCD-ABCD-ABCD

androidInstallUrl

URL used for eSIM installation for Android devices

string

https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$rsp-1234.example.com$ABCD-ABCD-ABCD-ABCD

brandingId

The unique ID of the branding assigned to the eSIM. If the default branding is used, the response will show “(default)”

string

f616f7g8-ey0d-123d-803d-0214a2f5dafb

profileName

The eSIM operator’s profile name

string

Profile 1

state

The current state of the eSIM

string

Allowed values: active suspended deactivated

active

lastDevice

The last device the eSIM profile was downloaded to or installed on. Omitted when not known.

object

imei

The International Mobile Equipment Identity of the device. Omitted when not known.

string

350089571234565

eid

The eUICC Identifier of the device’s embedded SIM. Omitted when not known.

string

89049032021008881300304741158317

tac

The Type Allocation Code of the device (the first 8 digits of the IMEI), which identifies its make and model. Omitted when not known.

string

35008957

make

The device manufacturer. Omitted when the TAC is not known or not recognised.

string

APPLE

model

The device model. Omitted when the TAC is not known or not recognised.

string

IPHONE DUO