Core Concepts

To effectively utilize 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 your global IoT service offering.

--------------------------------------------------------------------------------

What is a Service Profile ?

A Service Profile defines the set of services (data, sms etc) and network access capabilities (4G, 5G etc) that can be applied to an endpoint via plans

It is a named grouping of services and limits used to control what connectivity functions are available for an account or endpoint.

Service Profiles are created and must be assigned when creating a Base Plan or 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 changed afterward.

Related APIs

These are the REST APIs related to Service Profile operations.

• POST – Create Service Profile
  Service Profile [APIs] | POST-Service-Profile-–-Create

• GET – Retrieve Service Profile
  Service Profile [APIs] | GET-Service-Profile

Modify a Service Profile

• POST – Modify Service Profile
  Service Profile [APIs] | POST-Service-Profile-–-Modify

Delete a Service Profile

• POST – Delete Service Profile
  Service Profile [APIs] | POST-Service-Profile-–-Delete

What is a Rate Zone ?

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

Rather than setting prices or add-on rules for each individual network, SFT allows you to group networks into a single Rate Zone. This enables you to:

• Apply the same tariff across all networks in the group

• Make an addon available to all networks in the group

For example, if you want an addon to be available across a specific geographical region, you would:

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

2. Assign that Rate Zone to the addon definition

This simplifies the pricing and configuration model and avoids repeating the same tariffs or addon settings for each individual network.

Related APIs

The following APIs are used to manage Rate Zones:

• POST – Create Rate Zone
  Ratezone [APIs] | POST-Ratezone-–-Create

• GET – Retrieve Rate Zone
  Ratezone [APIs] | GET-Ratezone

• POST – Modify Rate Zone
  Ratezone [APIs] | POST-Ratezone-–-Modify

• POST – Delete Rate Zone
  Ratezone [APIs] | POST-Ratezone-–-Delete

What is a Base Plan ?

A Base Plan is the primary configuration assigned to an account or endpoint.
It defines how usage is charged, what services are available, and which coverage restrictions apply.

A Base Plan includes:

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

• Destination Group / Roaming Profile – defines which networks / countries the plan applies to

• Rate Zones & Tariffs – pricing rules applied to usage

• Notifications, Charges & Benefits – optional configuration for billing and messages

Key characteristics

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

• Single association: An endpoint can only have one Base Plan active at a time.

• Commercial scope: Base Plans define default pricing and allowances; they are central to billing

• Prepaid / Postpaid: Base Plans can be prepaid or postpaid depending on commercial setup

How Base Plans are used

When an endpoint is created, the associated plan influences:

• What services the endpoint can access

• Which networks it is allowed to use

• How usage is billed (based on tariff settings)

• What recurring charges apply

What is an Addon Plan ?

An Addon Plan is an optional commercial extension that provides additional benefits beyond the Base Plan. They are not replacements for Base Plans, but enhancements that operate in conjunction with them.

Addon Plans are typically used to:

• Provide extra data units or SMS allowances

• Introduce special benefits for a limited term

Key characteristics

• Multiple Addons: An endpoint/account may have one or more Addon Plans attached simultaneously.

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

• Precedence: Addon benefits are consumed before base plan benefits when both apply.

• Activation behaviour: Addons can be configured to activate:

  • On subscription – becomes active immediately upon assignment

  • On usage – only becomes active when first consumed

• Charge type: Addon plans may be:

  • One-time – charged once upon activation

  • Recurring – charged periodically

How Addon Plans are used

When a benefit is needed beyond what the Base Plan provides, an Addon Plan can be attached. Typical examples include:

• Extra data volume for a specific region

• SMS packs with distinct pricing

• Temporary allowances for seasonal campaigns

Addon Plan configurations often include:

• Service Profile (the allowed services for the addon)

• Priority (order of consumption relative to other addons)

• Benefits can be restricted by Rate Zones

• Optional notification

Plan APIs and Addon Assignment

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

• The Plan APIs (e.g., Create Plan, Update Plan) are used for both Base Plan and Addon Plan operations.

• When creating or updating a plan, the plan type (Base or Addon) determines how the plan behaves commercially and operationally.

Unique Identification of Addon Assignments

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

Each time an Addon is assigned:

• The system creates a distinct assignment instance

• This assignment instance receives a unique identifier

• This unique ID allows you to:

  • Track the assignment separately from other Addon assignments

  • Distinguish between multiple activations of the same Addon Plan

  • Apply actions (e.g., enable, disable, deactivate) against a specific assignment

This design enables use cases such as:

• Attaching the same Addon Plan multiple times to an endpoint with different validity periods

• Tracking usage, counters, or allowances per assignment

• Removing or modifying a specific assignment without affecting other Addon instances

API Implications

• When you assign an Addon to an endpoint, the API response will include a unique assignment ID

• That ID must be used in subsequent API calls that operate on the specific Addon assignment

• This pattern ensures traceability and unambiguous control of Addon behaviors in integrations

Related APIs

These APIs are used to manage plans (Base and Addon) in the SFT platform:

• POST – Create Plan
  Plan [APIs] | POST-Plan-–-Create

• GET – Retrieve Plans (Query Rate Plan)
  Plan [APIs] | GET-Plan-(Query-Rate-Plan)

• POST – Modify Plan
  Plan [APIs] | POST-Plan-–-Modify

• POST – Delete Plan
  Plan [APIs] | POST-Plan-–-Delete

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 in operational APIs and represents a managed device’s connectivity, billing, usage, and event context.

Unique Identifier

When an endpoint is created, the platform assigns a unique endpoint ID.
This ID is used in all API operations that reference a specific endpoint.

While SIM identifiers (such as ICCID, IMSI, or MSISDN) may be used at provisioning time, the endpoint ID is the key identifier for API calls.

Endpoint Lifecycle

An endpoint progresses through defined states:

• Pre-Active – Created but not yet active for network usage

• Active – Fully operational and able to generate usage

• Suspended – Temporarily disabled; connectivity is blocked

• Hold / Deactivated – Endpoint is removed or fully inactive

SIM state and connectivity behaviour follow the endpoint state.

Endpoint Operations via APIs

Most SFT API operations use the endpoint ID as the main reference. These include:

• Creating or modifying an endpoint

• Assigning or swapping SIMs

• Changing plans or attaching addons

• Retrieving usage, counters, and status

• Managing service configurations

• Triggering state changes (suspend, activate, deactivate)

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

• Plans define commercial and service configurations for the endpoint

• Service Profiles and Rate Zones influence allowed services and pricing

• Usage and events are aggregated per endpoint

Related APIs

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

👉 Endpoint APIs
Endpoint [APIs]