Webhook: eSIM Profile States

The following table covers possible eSIM state values that can be expected when working with the webhook type ESIM_STATUS

eSIM profile states vary depending on the product. At minimum, integrations must handle RELEASED, INSTALLED, and ERROR; all other states are product-dependent and may not be reported. The following diagram below illustrates a life cycle containing more of the eSIM's potential profile states.

Notes

  • The 'Deleted from device' decision point is because some of the products have a maximum limit of 5 reinstalls.
  • A transition to the UNKNOWN profile state can occur extremely rarely from any non-terminal state.

StateExplanationSuggested Display Message to end-userComment
RELEASEDThe eSIM is ready to be downloaded on the mobile device“eSIM is ready to be installed”May be received again if the eSIM was deleted from the device on a product that permits reinstallation.
DOWNLOADEDThe eSIM has been downloaded on the mobile device(Transient state, we do not recommend triggering behaviour or messages on this state)Not always reported. eSIM may go directly from RELEASED to INSTALLED.
INSTALLEDThe eSIM is installed on the mobile deviceIf the user has active balance:

“eSIM is installed and ready to be used”

otherwise:

“eSIM is installed, top up to use again”
 
ENABLEDThe eSIM is switched on in the mobile device and can be used if the mobile network allows

If the user has active balance:

“eSIM is active, ready to be used”

otherwise:

“eSIM is active but has no balance, top up to use again”

Not always reported. Some eSIM may only report INSTALLED status regardless of whether it’s enabled or disabled.
DISABLEDThe eSIM is switched off in the mobile device and not in use

If the user has active balance:

“eSIM is installed, turn on in settings to use”

else

“eSIM is installed but has no balance, top up to use again”

Not always reported. Some eSIM may only report INSTALLED status regardless of whether it’s enabled or disabled.
DELETEDThe eSIM has been deleted from the mobile device and can not be reinstalled.“eSIM has been deleted, please order a new one for your next trip”Not always reported. Terminal state. Products that permit reinstallation will return to RELEASED instead. DELETED is only reached when a reinstall limit is exhausted if applicable.
ERRORAn error occurred when the eSIM was installed on the device.“An error occurred during installation of your eSIM, contact support for a replacement” Terminal state.
UNKNOWNThe eSIM is in an unknown state.“We can not determine the status of your eSIM at this time. Please contact support if you are having problems connecting”

Did this page help you?