SIM for Things Portal
SIM for Things Portal
Breadcrumbs

Core Concepts – Commercial & Connectivity Models

To effectively use the SIM for Things (SFT) platform and its APIs, developers should understand the fundamental objects used for configuration, billing, and device management.

These core concepts work together to define how connectivity services are configured and consumed.


Service Profile

What is a Service Profile

A Service Profile is a named grouping of services (data, sms etc) and network access capabilities (4G, 5G etc) that are available for an account or endpoint

Service Profiles are created in advance and must be assigned when creating a Base Plan or an Addon Plan.

A Service Profile typically includes:

  • A name

  • One or more services (DATA, SMS-MO, SMS-MT, NB-IoT)

  • Access types (2G / 3G / 4G / 5G) defined per service

Once a Service Profile is created, it is selected during the Base Plan or Addon Plan setup and cannot be modified afterward.

A Service Profile defines:

  • Which services are allowed (e.g. data, SMS)

  • Which network technologies are supported (e.g. 4G, 5G)

These APIs are used to manage Service Profiles:

Rate Zone

What is a Rate Zone

A Rate Zone is a grouping of networks used to define how pricing and addon availability are applied across multiple destinations in SFT.

Instead of configuring pricing or addon rules per individual network, SFT allows networks to be grouped into a single Rate Zone. Tariffs and addons are then applied at the Rate Zone level.

This allows you to:

  • Apply the same tariff across all networks in the group

  • Make an addon available to all networks in the group

For example, to make an addon available in a specific geographical region:

  1. Define a Rate Zone containing all networks for that region

  2. Assign that Rate Zone to the addon configuration

This simplifies pricing and avoids repeating configuration per network.

The following APIs are used to manage Rate Zones:


Plans

Plans define the commercial configuration applied to endpoints.
SFT supports two types of plans: Base Plans and Addon Plans.

Base Plan

What is a Base Plan

A Base Plan is the primary commercial configuration assigned to an account or endpoint.

It defines:

  • How usage is charged

  • Which services are available

  • Which networks and coverage apply

A Base Plan typically includes:

  • Service Profile – allowed services (DATA, SMS, NB-IoT, etc.)

  • Destination Group / Roaming Profile – applicable networks or countries

  • Rate Zones & Tariffs – pricing rules

  • Notifications, Charges, and Benefits – optional billing configuration

Key characteristics

  • Mandatory: Every endpoint or account must have one Base Plan assigned before usage is billed

  • Single association: Only one Base Plan can be active per endpoint at a time

  • Commercial scope: Base Plans define default pricing and allowances

  • Billing type: Base Plans can be prepaid or postpaid

Addon Plan

What is an Addon Plan

An Addon Plan is an optional commercial extension that provides additional benefits beyond the Base Plan.

Addon Plans do not replace Base Plans; they operate in conjunction with them.

Typical use cases include:

  • Extra data volume

  • SMS bundles

  • Temporary or promotional allowances

Key characteristics

  • Multiple addons: An endpoint or account can have multiple Addon Plans attached

  • Multiple assignments: The same Addon Plan can be assigned multiple times to the same endpoint

  • Precedence: Addon benefits are consumed before Base Plan benefits

  • Activation behaviour:

    • On subscription – active immediately

    • On usage – activated upon first consumption

  • Charge type:

    • One-time

    • Recurring

Addon Plan configurations may include:

  • Service Profile

  • Priority (order of consumption)

  • Rate Zone restrictions

  • Optional notifications

Plan APIs and Addon Assignment

Both Base Plans and Addon Plans are created, modified, and managed via the Plan APIs.

The same APIs are used for both plan types; the plan type (Base or Addon) determines the behaviour.


Unique identification of Addon assignments

An Addon Plan can be assigned multiple times to the same endpoint.

Each assignment:

  • Creates a distinct assignment instance

  • Receives a unique assignment ID

This ID allows you to:

  • Track individual addon assignments

  • Distinguish between multiple activations of the same Addon Plan

  • Modify or remove a specific addon assignment independently

When assigning an Addon, the API response includes the assignment ID, which must be used in subsequent API calls.

These APIs are used to manage Base Plans and Addon Plans:

Endpoint

What is an Endpoint

An Endpoint is a unique connectivity instance in the SFT platform, typically associated with a SIM or eSIM.

It is the primary object used by operational APIs and represents a device’s:

  • Connectivity

  • Billing

  • Usage

  • Events

Unique Identifier

When an endpoint is created, a unique endpoint ID is assigned.

This ID is used in all API operations that reference the endpoint.
SIM identifiers (ICCID, IMSI, MSISDN) may be used during provisioning, but the endpoint ID remains the primary reference.

Endpoint Lifecycle

An endpoint can move through the following states:

  • Pre-Active – Created but not yet active

  • Active – Fully operational

  • Suspended – Temporarily blocked

  • Hold / Deactivated – Fully inactive

SIM state and connectivity behaviour follow the endpoint state.

Endpoint Operations via APIs

Most SFT APIs operate on the endpoint ID, including:

  • Creating or modifying endpoints

  • Assigning or swapping SIMs

  • Changing plans or attaching addons

  • Retrieving usage, counters, and status

  • Managing service configuration

  • Triggering lifecycle state changes

The endpoint ID is central to all integration flows.

How Endpoint Relates to Other Concepts 

Endpoint
  ├── Plan (Base Plan + Addon Plans)
  │     ├── Service Profile
  │     └── Rate Zones & Tariffs
  │
  ├── SIM (linked to endpoint)
  └── Usage / Events / Counters

All API operations related to Endpoint management are available on the following reference page:

👉 Endpoint APIs
https://iot-documentation.atlassian.net/wiki/x/zgDYLg