v1/esim_profiles

The v1/esim_profiles API is the basis for most of the eSIM actions and information available by the system.

• An eSIM profile (ICCID) is downloaded to a device using an activation code. After the activation code secret is validated by the carrier and eSIM provder, the profile is installed on the device.

• Once downloaded, an eSIM profile can be enabled to start using cellular service via the profile.

• Although the API separates the download, and enable actions, the UI will often call the combination of these two actions an activate request.

• eSIM profiles are created or deleted in the system only when the device reports successful profile actions

• eSIM profile actions are generally processed asynchronously and make take 3-10 minutes for the devices eSIM to contact the profile server (SM-DP+) and the eSIM registry (EIS). The APIs for delete, disable, download and enable return a transaction ID that can be used to monitor the progress of the action.

• eSIM profile multistep operations combine actions like download and enable into a single API call. Additionally, the multistep operation will wait for the device to successfully report the profiles after contacting the profile server and EIS. The multistep operation is most commonly used via an automation or template or the UI. A multistep operation may have multiple transactions.

The bulk API returns at most 20,000 records and sets the Truncated HTTP header if the data is truncated. Use the query parameter to limit the data returned.

URI

https://<hostname>/ws/v1/esim_profiles

Profile Formats

Profile action formats

Multistep operation formats

eSIM Profile Data

• carrier - The service provider network (SPN) of the eSIM profile
• customer_id - The account in which the eSIM profile is reported
• device_id - The device ID of the device that reported the eSIM profile
• eid - The eSIM’s EID.
• iccid - The ICCID of the eSIM profile
• id - The profile’s id number within the eSIM
• normalized_carrier - The normalized service provider network (SPN) of the eSIM profile (output only, created by the system for display and matching purposes)
• status - The status of the eSIM profile. Output only. Possible values are active, inactive.
• type - The type of eSIM profile, set by the service provider. Some possible values are operational, bootstrap, test.

eSIM Action Data

When requesting a download, enable, disable or delete action, specify the following payload:

• device_id - The device ID of the device that the action is applied to
• eid - The eSIM’s EID.
• iccid - Required for enable, disable and delete actions. If the activation code is registered with the system, then required for download.
• activation_code - The activation code secret. Only required if the activation code is not already registered with the system. If the activation code is already registered with the system, then use the iccid for download.

eSIM Profile Transaction Data

eSIM transaction statuses are checked when a progress API is called. The system intermittently checks the status of in-progress actions as well, marking those transactions as completed as appropriate.

• action - The action performed by the system on the device. Possible values are download, enable, disable, delete.
• created - The date and time the transaction was created
• customer_id - The account in which the eSIM profile is reported
• device_id - The device ID of the device that the action is applied to
• eid - The eSIM’s EID.
• iccid - The ICCID of the eSIM profile
• message_code - A short summary code describing the transaction message
• message - A message describing the status of the transaction from the system or profile server (SM-DP+) or eSIM registry (EIS)
• status - The status of the eSIM profile action. Possible values are in_progress, complete, failed, unknown.
• transaction - The unique identifier for the transaction.
• updated - The date and time the transaction was last updated

eSIM Multistep Operation Data

As the system processes multistep eSIM profile operations, it records debug and diagnostic information about the steps and progress. The system uses the service provider network (carrier) field to find an identify an appropriate activation code or profile to take action on.

• carrier - The requested service provider network (SPN) of the eSIM operation. Used to find a matching activation code or existing profile on the device.
• cause_id - The cause identifier like the automation ID or template ID.
• cause - The cause of the operation. Possible values are request, automation, template.
• created_by - The user or system service that initiated the operation
• created - The date and time the operation was created
• customer_id - The account in which the multistep operation is created
• device_id - The device ID of the device that the action is applied to
• download_tx - The transaction ID for the download operation.
• eid - The eSIM’s EID.
• enable_tx - The transaction ID for the enable operation.
• iccid - The ICCID of the eSIM profile requested.
• id - The identifier for the multistep operation
• job_id - The Remote Manager system job ID for the operation.
• message_code - A short summary code describing the transaction message
• message - A message describing the status of the transaction from the system or profile server (SM-DP+) or eSIM registry (EIS)
• operation - The operation being performed. Possible values are activate, download, enable
• source - The source API or system service that originated the request
• status - The overall status of the multistep operation. Possible values are starting, download, download_verify, enable, enable_verify, failed, successful.
• updated - The date and time the operation was last updated`

Parameters

Parameters for the v1/esim_profiles/inventory and v1/esim_profiles/bulk APIs include the following: