APIs CMO API Supported backends + features

Supported backends

CMO API currently supports several IoT BSS backends:

Network operatorBackendref as
Telekom DeutschlandM2M Service Portal 3.0TMSP
T-Mobile AustriaAeris IoT AcceleratorIOTA
Deutsche Telekom IoTAeris IoT AcceleratorIOTA
T-Mobile USCisco IoT Control CenterTMUS
EtisalatCisco IoT Control CenterJASPER
IntelsatIntelsatINTELSAT
JioCMO Management PlatformAIRLINQ
1NCE1NCE platform1NCE
STC (Saudi Telecom Company)ConnectMESTC
TurkcellTurkcellTURKCELL
ViasatGALAXY1GALAXY1

Some of these backends, such as M2M Service Portal 3.0 (TMSP), 1NCE and T-Mobile US Control Center (TMUS ICC), are used within the Deutsche Telekom group. Cisco IoT Control Center (Jasper) and Aeris IoT Accelerator (IoT-A), on the other hand, are platforms used by many different carriers worldwide.

IMPORTANT NOTE for 1NCE adapter: API calls to the /sims endpoints are now limited to 10 requests per second per organization. In that case you may receive “429 Too Many Requests” responses if the rate limit is exceeded. To prevent this, we recommend implementing a brief delay of around 100 milliseconds between successive API calls.

Retrieve paginated list of IoT Connection Products

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

IoT Connection Products are a composite of different subproducts, depending on the connectivity type, which could be cellular or satellite. Cellular products are composed by SIM Card, Data Connectivity and Usage Volume subproducts. Satellite products, on the other hand, contain Terminal and Usage Volume subproducts. This operation returns a paginated list of available products from all backend platforms configured for the tenant. The result set is paginated and it includes a summary of selected attributes for each product composite including

  • ID
  • Related Party (Platform account name in IoT Hub and account ID from external platform)
  • SIM Card or Satellite Terminal status
  • ICCID (for cellular products)
  • IMSI (for cellular products)
  • MSISDN (for cellular products)
  • Terminal Serial Number (for satellite products)
  • Terminal Name (for satellite products)
  • latitude (for satellite products)
  • longitude (for satellite products)

Retrieve details of IoT Product bundle with all products

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

Return detailed information about an IoT Connection Product and its bundled subproducts SIM Card or Satellite Terminal, Data Connectivity and Usage Volume. All available attributes for the target product can be returned, provided the respective data is supported by the backend.

Retrieve selected Products by Business ID

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

This operation returns a list of the products specified according to a business ID, which depends on the connectivity type of product. For cellular the ICCID is used as business ID and for satellite terminal the business ID is the serial number instead. The result set includes the full details for each product as in the result of the previous operation.

Retrieve details of SIM Card

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

Return detailed information about a SIM Card subproduct. Detailed information about the SIM Card is returned, depending on the supported data provided by backed system:

  • ICCID
  • IMSI
  • MSISDN
  • Status
  • other attributes specific for each backed system

Retrieve details of Satellite Terminal

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

Return detailed information about an Terminal subproduct. Following details are currently supported:

  • Terminal serial number
  • Terminal name
  • Status
  • Latitude
  • Longitude
  • Model
  • Mobility type
  • Antenna code
  • Last update date
  • Imo number
  • mmsi

Retrieve details of Data Connectivity service

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

Return detailed information about a Data Connectivity subproduct. Detailed information about the realted data connectivity services is returned, depending on the supported data provided by backed system:

  • Network provider
  • Data connectivity type (e.g. LTE, GRPS, NB-IoT, etc)
  • Communication plan
  • List of APNs

Retrieve information on consumed usage for a product

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

Retrieve the current consumption of a product. Consumption might be provided for the current billing period or for the current month, depending on the backend platform and on the kind of service provided by the respective carrier (e.g. prepaid or postpaid). The information is returned in a standardized volume bucket structure as defined by TM Forum SID.

The Consumption Bucket is categorized into three distinct levels: global, cellular and satellite.

  1. Global Level: This level represents the aggregate data usage. It combines the data from both cellular and satellite sources.

  2. Cellular Level: This level exclusively tracks the usage of cellular data. When cellular data is utilized by the user, the consumption is specifically accounted for under this level.

  3. Satellite Level: Similar to the Cellular Level, this level is dedicated to monitoring the usage of satellite data.

In scenarios where both cellular and satellite data are used, the system will display three separate Consumption Buckets: one for cellular, one for satellite, and one for the combined total, represented as the global level. However, in cases where the consumption is solely from cellular data with no usage of satellite data, the global level will be used to display the total consumption. This global level will encompass all cellular data usage, excluding any satellite data.

Change the status of SIM Card product

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

API clients can request the change of the Status of a SIM Card by addressing the respective SIM Card Product. Different status terminologies used by the integrated systems are normalized and standardized according to TM Forum SID.
Overview of all supported statuses and the respective backend in which the status changes is implemented over CMO API is provided below:

  • CREATED
  • PENDING_ACTIVE
  • INVENTORY
  • ACTIVE
  • SUSPENDED
  • BLOCKED
  • PENDING_TERMINATE
  • TERMINATED
  • DELETED
  • UNKNOWN

The following SIM Card status transitions diagram applied for all integrated platforms: Data structures

Supported statuses and allowed transitions are managed by the underlying backend system, which means what status transition is actually possible for an individual SIM Card product will depend on the business rules of the commercial product implemented in the backend management system.

Considering that, the following transitions are implemented and can be triggered from CMO API according to the platform.

TMSPTMUSIOTAJASPERAIRLINQ1NCESTCTURKCELLVIASAT
CREATED
→ ACTIVE
PENDING_ACTIVE
→ ACTIVE
ACTIVE
→ SUSPENDED
SUSPENDED
→ ACTIVE
PENDING_TERMINATE
→ ACTIVE
ACTIVE
→ BLOCKED
BLOCKED
→ ACTIVE
ACTIVE
→ TERMINATED
TERMINATED
→ ACTIVE

The actual fulfillment will depend on the business rules of the tariff in the backend system.

Change the status of a Satellite Terminal

INTELSAT
ACTIVE → SUSPENDED
SUSPENDED → ACTIVE

API clients can request the change of the status of a Satellite Product by addressing the respective Terminal Product. Different status terminologies used by the integrated systems are normalized and standardized according to TM Forum SID. Satellite products are only available for Intelsat backend and transitions within the statuses below are supported:

  • ACTIVE
  • SUSPENDED

Connectivity product status mapping between CMO API and integrated systems

If necessary to compare real SIM Card status from backed system with common status in CMO API, then the following table could be used as a reference:

IoT Hub StatusTMSPTMUS and JASPERIOTA
CREATEDOrdered
Ordered for Stock
INVENTORYOn StockINVENTORY
PENDING_ACTIVEDeliveredACTIVATION_READYACTIVE_NO_BILLING
ACTIVETest
Productive
ACTIVATED
TEST_READY
ACTIVE
SUSPENDEDSuspendedDEACTIVATEDDEACTIVATED
BLOCKEDBlocked(automatically)
Blocked(manually)
Blocked(by operator)
PENDING_TERMINATERETIREDDEACTIVATED_NO_BILLING (billing inactive)
TERMINATEDTerminatedPURGEDTERMINATED
DELETEDDeleted
UNKNOWNUndefined
IoT Hub StatusAIRLINQ1NCESTC
CREATEDTEST
INVENTORY
PENDING_ACTIVEREADYINACTIVE
ACTIVEACTIVEEnabledACTIVE
SUSPENDEDSUSPENDDisabledSUSPENDED
BLOCKEDBLOCKED
PENDING_TERMINATECEASE
TERMINATEDTERMINATED
DELETED
UNKNOWN

Turkcell platform doesn’t have a separate status for the SIM Card. Table below represents rules for status calculation in CMO API. Turkcell SIM Card status consists of line status, SIM Card status and SMS, calls and data barred/unbarred state:

IoT Hub StatusTurkcell contract statusIn SMS barredOut SMS barredIn Calls barredOut Calls barredData barred
ACTIVEaNNNNN
SUSPENDEDaY (opt.)Y (opt.)Y (opt.)Y (opt.)Y (opt.)
TERMINATEDd

For Satellite terminal status in CMO API used a combination of a Product Contract status and terminal aggregated status in Intelsat:

IoT Hub StatusINTELSAT Product Contract statusINTELSAT Satellite terminal aggregated status
CREATEDnew (and change actions allowed)
PENDING_ACTIVEnew (and change actions are not allowed)
ACTIVEactiveonline
SUSPENDEDactivesuspended
SUSPENDEDsuspended
BLOCKEDactiveoffline
PENDING_TERMINATEcancelation
TERMINATEDended

Update selected characteristics or attributes of target IoT Product

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

API clients can update specific product characteristics of target IoT Product or Subproduct (SIM Card or Data Connectivity characteristics). Updatable product characteristics depend on the backend system. Currently only products managed by TMSP can have their characteristics changed and following ones are supported:

  • Product offering
  • Related Party
  • SIM Card Product characteristics (SIM profiles)

Create custom attribute for a SIM card subproduct

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

CMO API allows clients to add custom properties to the individual SIM Card products. Properties are defined as pair of name and value and both can be defined by the API client. The information is stored locally in CMO only and it is independent of the backend system that manages the product.

Retrieve Custom Attributes

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

Retrieve custom attributes for a specific SIM Card. It is possible to retrieve all custom attribute or only selected ones according to the name.

Update Custom Attributes

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

Update value or name of individual custom attributes assigned to a SIM Card.

Delete Custom Attributes

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

Delete invidual custom attributes assigned to a SIM Card.

Batch Update

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

For selected backends it is possible to trigger an operation that applies to a list of products in a single request. All products should belong to the same backend platform account.

Monitor the Status of Asynchronous Requests

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

Depending on the backend, specific operations are processed asynchronously. That happens in case of triggering a status update, or in case of batch operations, and this means the backend accepts the request but doesn’t execute it immediately. In those cases CMO API provides a monitor ID that can be used to track the processing status of the respective batch operation.

Terminate Asynchronous Requests

TMSPTMUSINTELSATIOTAJASPERAIRLINQ1NCESTCTURKCELLGALAXY1

For asynchronous operations that were not yet processed it is possible to send an API request to cancel its execution.