IoT Connect API integration

This article explains how to integrate our APIs for the IoT Connect offer, with pay-per-use or pooled bundles. If you use IoT Connect Capped Plans, see IoT Connect Capped Plans API integration.

Before you start: read How to integrate our APIs? to get your credentials and find your service profiles and technical values in the SIM Management Platform. API links and references are on the Developer Portal.

1. Which APIs do you need?

You can get started with just a few calls.

Type	API	What it does
Required	Authentication	Gets your access tokens.
Required	Connectivity Management	Activates, suspends or terminates SIMs, changes their services, fills in reference and group fields, and reads a SIM’s service information.
Required	SIM Search	Searches, filters, sorts and paginates your SIMs.
Recommended	Network Usage	Retrieves the usage of 1 to 5 SIMs over a period.
Recommended	Webhooks	Notifies you when an asynchronous action is complete.
Optional	SIM Management	Retrieves eSIM details, for consumer eSIMs.
Optional	Network APIs (diagnostics)	Runs one-off network attach and data session checks.

OCS APIs do not apply. IoT Connect with pay-per-use or pooled bundles does not use the Online Charging System (OCS), so the OCS APIs cannot be used with this offer.

2. Activate your SIMs and manage their services

API: Connectivity Management

In IoT Connect, pay-per-use and each pooled bundle are rate plans, and the services applied to a SIM (SMS, data, roaming…) are options. A service profile combines the two: one rate plan and a value for each option.

Recommended: use service profiles

Create or pick a service profile in the SIM Management Platform, then pass its reference in the activation request. The SIM gets the profile’s rate plan and services, and appears under that profile in the interface, exactly as if you had activated it there.

POST /api/subscribers/sim-serial/{simSerial}/activate
{
  "serviceProfile": "<your service profile reference>",
  "externalReference": "Device-0001",
  "group": "Group A1"
}

To change a SIM’s services, or move it to another pooled bundle, assign it another service profile. The SIM takes on the new profile’s configuration and is not marked as deviated. It stays aligned with its profile and sorted correctly in the interface.

Alternative: use a rate plan and options

If you need a specific configuration for each SIM, pass the rate plan and the technical label of each option.

For example, to bar all outgoing SMS on a pay-per-use SIM, your call includes the rate plan (to identify the offer), then the option that bars outgoing SMS:

{
  "ratePlan": "M2MA_WW_TSL_PPU_5",
  "options": [
    {
      "name": "M2M_TSL_BAR_SCP_ALL_OUTGOING_SMS",
      "value": "on"
    }
  ]
}

⚠️ Changing a SIM’s options one by one marks it as deviated from its service profile in the SIM Management Platform. To change services without deviating your SIMs, assign them another service profile instead.

Good to know:

• Some options accept only one value, like a drop-down list in the interface. For example, Outgoing SMS can be Enabled, Disabled or Enabled for on-net SMS only.
• Each option has a default value if you don’t set it. For Outgoing SMS, the default is Enabled.

3. Find the values to use in your API calls

• Service profiles: in the SIM Management Platform, go to Services > Service profiles and copy the profile reference.
• Rate plans and options: go to Catalogue > Options. This menu lists the exact technical labels of the offer’s options. If your contract includes several rate plans (for example, several pooled bundles), select one from the drop-down list.

These are the same values that make up a service profile in the interface.

4. Retrieve your SIM list

API: SIM Search

Search, filter, sort and paginate your SIMs. Typical uses include inventory dashboards, customer portals, internal tools, retrieving SIMs by account or group, and customer care and troubleshooting workflows.

5. Get notified with webhooks

Many actions are asynchronous (an activation can take a few minutes). Register an endpoint with the Webhooks API to receive an event when a change is complete. For IoT Connect, the main events are the Connectivity Management events.

6. Retrieve data usage

API: Network Usage

Retrieve the usage of 1 to 5 SIMs over a period, either as CDRs or already aggregated. You can filter and break down usage by:

• interval (hourly, daily, monthly);
• breakdown (APN, country or radio access type);
• date and country of origin;
• MCC / MNC;
• IP address (recommended only for SIMs with a fixed IP);
• service outcome.

7. Optional APIs

eSIM details – if you use eSIM profiles

API: SIM Management, Get eSIM details endpoint only

If you use consumer eSIMs, this endpoint returns the activation code, the QR code download link, the eSIM status and the device status (useful for troubleshooting). The Reserve and Release profile APIs do not apply to IoT Connect: your profiles are already reserved and released.

Diagnostics

The Network APIs (Network Attach, Data Session) let you run the same checks as in the SIM Management Platform. They are for one-off checks only and cannot be used to query your whole fleet automatically. A stricter rate limit applies.

Glossary – values for IoT Connect

Our API documentation is generic and doesn’t list the values specific to each offer. Here are the ones to use for IoT Connect.

Value	Used in	What to enter
serviceProfile	Connectivity Management (activation, service change)	Your service profile reference, from Services > Service profiles
ratePlan	Connectivity Management (rate plan + options method)	Your pay-per-use or pooled bundle rate plan, from Catalogue > Options
options	Connectivity Management (rate plan + options method)	The technical label (name) and value of each option, from Catalogue > Options

Need help?

Contact our support team via the Service Desk.