Skip to main content

API for SGP.32

SGP.32 is the GSMA specification for remote SIM provisioning in IoT. SGP.32 introduces a modern, standardized way to manage eSIM profiles remotely, making it easier to provision, activate, change, and manage connectivity throughout the lifecycle of a device.

For business customers, SGP.32 enables more flexible and scalable SIM management. It can simplify large-scale deployments, reduce the need for physical SIM handling, support remote operations, and make it easier to manage connectivity across different markets, networks, and device types.

This page provides an overview of the APIs Telenor IoT is offering for managing SIMs in an SGP.32 environment. The APIs allow you to integrate eSIM lifecycle management into your own systems and applications.

Key SGP.32 Concepts​

Before working with the APIs, it is useful to understand a few core concepts:

  • eSIM/eUICC – The secure hardware component in the device that stores and manages eSIM profiles. An eUICC-capable SIM can be called both an eUICC and an eSIM, the terms refer to an eUICC-capable SIM card of any form factor.
  • EID – The unique identifier of an eSIM. It identifies the eSIM hardware in a device and is used to associate profiles and provisioning operations with the correct eSIM.
  • Profile – A digital SIM configuration containing the operator credentials required for a device to connect to a mobile network. An eSIM can store multiple profiles, but only one profile can be enabled and used by the eSIM. An eSIM profile needs a subscription in the operator's Connectivity Management Platform to be able to attach to a network and use the services.
  • Activation code – A string used in the backend systems to initiate the download of a profile to an eSIM.
  • IPA – Embedded IoT Profile Assistant is the component that manages the eSIM IoT profile lifecycle on behalf of the device/application, including profile download, installation, enablement, and related management functions. The IPA can be embedded in the SIM, IPAe, or in the device, IPAd. Telenor IoT's SGP.32 SIM comes with an IPAe.
  • eIM – The eSIM IoT Remote Manager is the platform that manages remote provisioning operations for IoT eSIMs, such as instructing the eSIM to download, enable, disable, or delete profiles.
  • SM-DP+ – The Subscription Manager Data Preparation Plus component is responsible for preparing and securely delivering eSIM profiles for download.

Polling, Download and Enable​

In an SGP.32 deployment using IPAe, the eSIM periodically polls the eIM for pending operations. The polling connection is established through a dedicated polling APN. Telenor IoT’s dedicated polling APN is configured with whitelisting to allow communication only to approved eIM and SM-DP+ endpoints. This provides a controlled connectivity path for provisioning traffic while achieving separation for the normal mobile data connection. The whitelisting means that all SM-DP+ endpoints from which profiles should be downloaded need to be added to the whitelist before the download can be carried out.

When an operation has been initiated, it will remain active in the eIM until the validity period of the operation expires, or the eSIM uses the IPAe connection to poll the eIM and retrieve the information required to initiate the operation. An operation can download, enable, or delete a profile.

For download, the eSIM will first poll the eIM to fetch the download operation and retrieve the activation code. Then the eSIM will connect to the SM-DP+ and download the profile to the eSIM, using the same APN as for polling.

Once the profile has been downloaded, it can be enabled on the eSIM, which means that the device will switch to the connectivity provided by the newly enabled profile.

When a profile is no longer needed on the eSIM, it can be deleted from the eSIM. To avoid unnecessary costs, make sure that the subscription of the eSIM profile is terminated before the profile is deleted. The enabled profile cannot be deleted.

Telenor IoT offers a wide range of API calls that will allow customers to fully automate their eSIM lifecycle.

Available API Calls​

The sections below describe the available APIs related to SGP.32 SIM management. The first link in each section takes you to the detailed API documentation for each API call.

Please visit this page for more information on API Authentication: IoT Connect Authentication.

Order Activation Code APIs​

Create an Activation Code Order​

API Documentation: Create a new activation code order

Use this endpoint when you need to create an activation code order for SGP.32 eSIM profiles. This is used when you want to request activation codes that allow you to download a Telenor IoT profile to an existing SGP.32 eSIM.

Endpoint

POST https://api.iot.telenor.com/iot-connect/orders/v1/activation-codes

The request must contain the parameters defining the activation codes that you want to order:

  1. domainId is the ID of the domain where the activation code subscriptions should be provisioned
  2. orderParams:
    • quantity is the number of activation codes you want to order
    • simProfileId defines the kind of profile that you are ordering. Each Domain has access to one or more eSIM profile configurations identified by a simProfileId
    • servicePolicyId defines which Service Policy/Subscription Package (SP) that the profiles will be on. The SP can be changed after order has been fulfilled
    • mode can be ACTIVE or DEACTIVATED depending on if you want the subscriptions to be network active on delivery. For a successful enable the mode of the subscription must be ACTIVE when the profile is enabled on the eSIM
  3. orderNote is a free text field to help you identify the order

The response contains a requestId that can be used to retrieve information about the order’s status.

Parameter Source: Retrieve domainId​

API Documentation: List Domains

Use this endpoint when you need to retrieve the domains in your hierarchy.

Endpoint

GET https://api.iot.telenor.com/identity-access-management/domains

The call takes multiple optional parameters which allow you to limit the number of domains returned by the API, which is useful if the API user has access to many domains.

Use the domainId to create an activation code order on the right domain.

Parameter Source: Retrieve simProfileId​

API Documentation: Get SGP.22/32 SIM Profiles

Use this endpoint when you need to retrieve the Id of the SGP.22/32 eSIM profiles available in a specific domain. This call is used to retrieve the simProfileId which is used as input parameter when placing an order for activation codes, to identify which “template” you wish to use for the profiles you order.

Endpoint

GET https://api.iot.telenor.com/iot-connect/subscriptions/v1/sim-profiles

The only optional parameter is the domain ID. If no domain ID is provided, the API returns the SIM profiles belonging to the user's default domain. To retrieve profiles for a specific domain, provide the domain ID in the call.

Parameter Source: Retrieve servicePolicyId​

API Documentation: Get All Service Policies

Use this endpoint to retrieve all Service Policies/Subscription Packages (SP) that are available on the domain. The Service Policy is needed as input parameter to create an activation code order.

Endpoint

GET https://api.iot.telenor.com/iot-connect/service-policies/v1/iot-platform

The call takes multiple optional parameters which allow you to filter the results if the user has access to multiple domains or a domain has many SPs.

Retrieve Information About Multiple Activation Code Orders​

API Documentation: Retrieve Activation Code Orders

Use this endpoint when you need to retrieve existing activation code orders. It is useful after creating an activation code order, for checking the order status, or to retrieve the current information about one or more orders.

note

This call retrieves information about the order, not the activation codes. Use Get activation codes API to retrieve the activation codes.

Endpoint

GET https://api.iot.telenor.com/iot-connect/orders/v1/activation-codes

The endpoint supports optional parameters domainId and orderStatus that can be used to filter the activation code orders returned by the API. The response contains a list of matching activation code orders.

If no filters are required, the endpoint can be called without parameters to retrieve all activation code orders for the domains that the user has access to.

Retrieve Information About One Activation Code Order​

API Documentation: Retrieve an Activation Code Order

Use this endpoint when you need to retrieve the details of one specific activation code order. This is typically used after creating an activation code order, when you have received the order ID and want to check the order status or retrieve its details.

note

This call retrieves information about the order, not the activation codes. Use Get activation codes API to retrieve the activation codes.

Endpoint

GET https://api.iot.telenor.com/iot-connect/orders/v1/activation-codes/:orderId

The orderId parameter is required and identifies the activation code order you want to retrieve. The order ID is obtained from the URI received when the order was created, or from the list returned by Retrieve activation code orders.

Retrieve Activation Codes APIs​

Get Activation Codes​

API Documentation: Get Activation Codes for SGP Profiles

Use this endpoint when you need to retrieve the activation codes. The activation codes can be used to download the corresponding eSIM profile onto an eSIM.

Endpoint

GET https://api.iot.telenor.com/iot-connect/subscriptions/v1/sgp-profiles

No parameters are required for this call, but you can use multiple parameters to filter the returned activation codes:

  • activationCodeStatus=UNUSED will ensure you only get activation codes that are ready to be downloaded to an eSIM.
  • orderId parameter to only get the activation codes of a specific order.

There are limit parameters that can be used to restrict the number of activation codes that are returned.

The endpoint retrieves the requested eSIM profiles together with their corresponding activation codes.

Download Activation Codes as a CSV File​

API Documentation: Download Activation Codes for SGP Profiles

Use this endpoint when you need to download activation codes profiles as a CSV file rather than get them as a JSON response. This is useful when activation codes need to be exported for further processing, storage, or distribution as part of an eSIM provisioning workflow.

The downloaded file contains the eSIM profiles matching the query and their corresponding activation codes. The activation codes enable profile downloads on eSIMs.

Endpoint

GET https://api.iot.telenor.com/iot-connect/subscriptions/v1/sgp-profiles/download

No parameters are required for this call, but you can use multiple parameters to filter the returned activation codes:

  • activationCodeStatus=UNUSED will ensure you only get activation codes that are ready to be downloaded to an eSIM.
  • orderId parameter to only get the activation codes of a specific order.

There are limit parameters that can be used to restrict the number of activation codes that are returned.

The endpoint retrieves the requested eSIM profiles together with their corresponding activation codes, as a CSV file.

eIM Operation APIs​

Start Profile Download​

API Documentation: Start Download Profile Request

Use this endpoint when you need to initiate the download of new eSIM profiles to a list of eSIMs. The call starts the profile download process for all eSIMs specified in the request, up to 10 000 items per request.

Endpoint

POST https://api.iot.telenor.com/iot-connect/subscriptions/v1/eUICCs/change/download-profile

The request requires the following parameters:

  • items is an array of the activation code and target eSIM, specifying which profile (defined by an activationCode) to be downloaded to which eSIM (defined by an eid).
  • validityPeriod specifies how long the download request should remain valid, specified in seconds. If no value is provided, the default of 30 days is used. The maximum is 90 days.
  • enableProfile should be set to true if the profile should be enabled automatically after download. If omitted, the default is false.
  • preferIndirectDownload will allow you to choose the indirect download method, where the eIM acts as an intermediary between the SM-DP+ and the eSIM. This parameter currently has no effect because the indirect download method is not yet implemented. It can be omitted and the default value false will be used.

The response contains a requestId that can be used to retrieve information about the request’s status.

Start Profile Enablement​

API Documentation: Start Enable Profile Request

Use this endpoint after a profile has been downloaded to an eSIM and you want to make that profile the enabled profile. This action will make the operator of the downloaded profile the connectivity provider for the eSIM. Make sure that the profile to be enabled has an ACTIVE subscription in the operator’s Connectivity Management Platform. The ICCID must be present on the eSIM for the enable action to be carried out. The call can be used for multiple eSIM, up to 10 000 items per request.

Endpoint

POST https://api.iot.telenor.com/iot-connect/subscriptions/v1/eUICCs/change/enable-profile

The request takes the following parameters:

  • items is an array of target eid and iccid that should be enabled.
  • validityPeriod specifies how long the enable request should remain valid, specified in seconds. If no value is provided, the default of 30 days is used. The maximum is 90 days.

The response contains a requestId that can be used to retrieve information about the request’s status.

Start Profile Deletion​

API Documentation: Start Delete Profile Request

Use this endpoint to initiate request to delete one or more eSIM profiles, specified by ICCID, from specified eSIMs. The ICCID must be present on the eSIM for the delete action to be carried out. The call can be used for multiple eSIM, up to 10 000 items per request.

Endpoint

POST https://api.iot.telenor.com/iot-connect/subscriptions/v1/eUICCs/change/delete-profile

The request takes the following parameters:

  • items is an array of target eid and iccid of the profile that should be deleted from the eSIM.

The response is a requestId that can be used to retrieve information about the request’s status.

Retrieve Subscription Requests (eIM Operations)​

API Documentation: Get Subscription Requests

Use this endpoint to retrieve a list of subscription requests associated with the account. The call fetches a list of subscription requests, with optional filtering, pagination, and sorting.

Endpoint

GET https://api.iot.telenor.com/iot-connect/subscriptions/v1/requests

No parameters are required for this call, but you can use multiple parameters to filter the returned list of subscription requests:

  • Filtering can be done on status, requestType, startDate and endDate.
  • You can also choose to sort the response based on dates or status.

Retrieve One Subscription Request​

API Documentation: Get Subscription Request by ID

Use this endpoint to retrieve the status of one subscription request.

Endpoint

GET https://api.iot.telenor.com/iot-connect/subscriptions/v1/requests/:requestId

The request takes the requestId as a parameter.

The response will include details of the requestId, that is, requestType, status and which user created the request and when.

Retrieve One Subscription Request with Items​

API Documentation: Retrieve Subscription Request with Items

Use this endpoint to retrieve the status of one subscription request including the items, the target EID and ICCID or activation code.

Endpoint

GET https://api.iot.telenor.com/iot-connect/subscriptions/v1/requests/:requestId/items

The request takes the requestId as a parameter.

The response will include details of the requestId, that is, requestType, status and which user created the request and when, also including an array of the items that were targeted by the request, including status for each item.