Endpoint Activation & Addon Provisioning

A traveler logs in to Customer X’s portal and purchases a new eSIM with a connectivity add-on.

User authentication, identity verification, and payment handling are managed entirely by Customer X’s portal and are out of scope for SFT.

Once the purchase is completed, Customer X must:

• Assign an available eSIM to the traveler

• Activate the corresponding endpoint

• Deliver the eSIM installation details (QR code) to the traveler

Objectives

• Allocate an unused, pre-created endpoint

• Activate the endpoint so connectivity can start

• Assign Addon

• Provide the traveler with the eSIM QR code required to install the profile on their device

At the end of this process:

• The endpoint is active

• The addon customer purchased is assigned

• The eSIM is installable by the traveler

• The endpoint is ready to connect using addon

High-Level Flow

1. Identify an available eSIM / endpoint

2. Activate the endpoint

3. Assign Addon

4. Deliver eSIM installation details to the traveler

Step 1 – Find an Available eSIM

Customer X needs to identify the first available eSIM that is:

• Not yet used by any traveler

• Already linked to a pre-created endpoint

• Ready to be activated

Although Customer X can manage this selection using its own backend inventory, this section explains how the same information can be retrieved using SFT APIs.

Customer X can retrieve available eSIMs by calling the GET SIM (fetchSIM) API with specific query parameters.

• simStatusId = 12

Indicates that the SIM is in Pre-Active state

• simAttachStatusId = 1

Indicates that the SIM is already attached to an endpoint

To retrieve only one SIM, you can use

• page = 1

• perPage = 1

So the final api call must be

https://sft.bics.com/api/fetchSIM?simStatusId=12&simAttachStatusId=1&page=1&perPage=1

This ensures that only the first available SIM is returned.

Key Output Data

From the API response, Customer X can retrieve the following key values:

• endpointId
  The identifier of the endpoint associated with the SIM
  → Used in the activation step

• iccid
  The eSIM identifier
  → Can be used for internal tracking and activation logic

• msisdn (optional)
  The MSISDN associated with the SIM
  → Can be exposed to the traveler if required

• activationCode.textQrCode
  A string representing the Consumer eSIM profile activation code
  → Used to generate a QR code for eSIM installation

Customer X uses this value to generate and deliver the QR code to the traveler via its portal or communication channels.

Step 2 – Activate the Endpoint

Once an available eSIM and endpoint are identified, Customer X must activate the endpoint so that:

• The eSIM can connect to the network

• Add-ons can later be provisioned

• Usage can be generated

Customer X can activate the endpoint using one of the following APIs:

Option 1 – Endpoint Activate API

• Activate the endpoint directly

• Uses endpointId in the request body

Option 2 – EndpointLifeCycleChange API Recommended

• Uses endpointId in the request body

• Sets lifecycle state to A (Active)

The EndpointLifeCycleChange API is recommended because:

• It provides a consistent way to manage endpoint lifecycle

• The same API can later be reused to deactivate or suspend the endpoint

Step 3 – Add-on Provisioning

After the endpoint has been activated, Customer X must provision the add-on purchased by the traveler.

At this point:

• The traveler has completed a purchase in Customer X’s portal

• The endpoint is active

• Customer X knows which add-on was purchased

During the Backend Configuration – Initial Setup phase, Customer X created all add-ons in SFT and stored a mapping between:

• Portal add-on products

• SFT planId values

for example:

Using this existing mapping, Customer X can now assign the purchased add-on to the activated endpoint.

Customer X assigns an add-on to an endpoint by calling the POST SubscribeAddon API.

The request body must include:

• endpointId
  Identifies the endpoint to which the add-on will be assigned

• planId
  Identifies the add-on plan to be assigned
  This value is retrieved from Customer X’s backend mapping created during the configuration phase

Key Output Date

If the operation is successful, the API response includes a unique identifier for the add-on instance:

• uniqueId (info.promotionalPlans.plan.uniqueId)

Customer X must store and use the uniqueId to:

• Track the remaining balance of a specific add-on

• Display correct usage information in the portal

• Handle renewals, expirations, or deactivations

• Distinguish between multiple active add-ons of the same type

For more information about uniqueId see in Appendix https://iot-documentation.atlassian.net/wiki/spaces/SAOG/pages/791150620/Endpoint+Activation+Addon+Provisioning#Understanding-planId-vs-uniqueId

Repeated Add-on Purchases

The same add-on provisioning procedure applies every time a traveler purchases an add-on, regardless of whether:

• The traveler purchases a new add-on, or

• The traveler purchases the same add-on again

Each purchase results in:

• A new add-on assignment to the endpoint

• A new add-on instance with its own uniqueId

• Independent validity and balance tracking

Customer X should therefore repeat Step 3 – Add-on Provisioning for:

• Initial add-on purchase

• Add-on renewal

• Additional add-on purchases during the same trip

Step 4 – Deliver eSIM to final customer

After the endpoint has been activated and the add-on has been provisioned, Customer X must enable the traveler to install the eSIM profile on their device.

This is achieved by delivering the eSIM installation details, typically in the form of a QR code, to the traveler.

When Customer X retrieved the available SIM during Step 1 – Find an Available eSIM, the response included the following value:

• activationCode.textQrCode

This field contains the Consumer eSIM profile activation data required to install the eSIM on a device.

SFT does not handle QR code generation or delivery to the end user.

Customer X is responsible for:

• Generating a QR code from activationCode.textQrCode

• Delivering the QR code securely to the traveler

Delivery methods are entirely controlled by Customer X and may include:

• Displaying the QR code in the customer portal

• Sending it via email or SMS

• Providing it through a mobile application

Appendix

Understanding planId vs uniqueId

This distinction is critical for correct add-on lifecycle management.

planId – Add-on Definition

• Represents the add-on product definition

• Created once during backend configuration

• Reused every time the same add-on is assigned

Example:

• “30 GB – 7 Days – Country A”
  → one planId

uniqueId – Add-on Instance

• Represents a specific instance of an add-on assigned to an endpoint

• Generated every time the add-on is assigned

• Uniquely identifies that assignment

If the same add-on is assigned multiple times to the same endpoint, each assignment results in a new instance with a different uniqueId.

Example Scenario

A traveler purchases the same add-on three times:

• All three assignments use the same planId

• Each assignment generates a different uniqueId

• Each uniqueId represents a distinct add-on instance with its own:

  • Validity

  • Balance

  • Lifecycle