APIs CMO API Supported backends + features
Supported backends
CMO API currently supports several IoT BSS backends:
Network operator | Backend | ref as |
---|---|---|
Telekom Deutschland | M2M Service Portal 3.0 | TMSP |
T-Mobile Austria | Aeris IoT Accelerator | IOTA |
Deutsche Telekom IoT | Aeris IoT Accelerator | IOTA |
T-Mobile US | Cisco IoT Control Center | TMUS |
Etisalat | Cisco IoT Control Center | JASPER |
Intelsat | Intelsat | INTELSAT |
Jio | CMO Management Platform | AIRLINQ |
1NCE | 1NCE platform | 1NCE |
STC (Saudi Telecom Company) | ConnectME | STC |
Turkcell | Turkcell | TURKCELL |
Viasat | GALAXY1 | GALAXY1 |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✖ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✖ | ✖ | ✔ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✔ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✖ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✖ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
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.
Global Level: This level represents the aggregate data usage. It combines the data from both cellular and satellite sources.
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.
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✖ | ✔ | ✔ | ✔ | ✔ | ✔ | ✖ | ✖ |
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:
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.
TMSP | TMUS | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | VIASAT | |
---|---|---|---|---|---|---|---|---|---|
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 Status | TMSP | TMUS and JASPER | IOTA |
---|---|---|---|
CREATED | Ordered Ordered for Stock | ||
INVENTORY | On Stock | INVENTORY | |
PENDING_ACTIVE | Delivered | ACTIVATION_READY | ACTIVE_NO_BILLING |
ACTIVE | Test Productive | ACTIVATED TEST_READY | ACTIVE |
SUSPENDED | Suspended | DEACTIVATED | DEACTIVATED |
BLOCKED | Blocked(automatically) Blocked(manually) Blocked(by operator) | ||
PENDING_TERMINATE | RETIRED | DEACTIVATED_NO_BILLING (billing inactive) | |
TERMINATED | Terminated | PURGED | TERMINATED |
DELETED | Deleted | ||
UNKNOWN | Undefined |
IoT Hub Status | AIRLINQ | 1NCE | STC |
---|---|---|---|
CREATED | TEST | ||
INVENTORY | |||
PENDING_ACTIVE | READY | INACTIVE | |
ACTIVE | ACTIVE | Enabled | ACTIVE |
SUSPENDED | SUSPEND | Disabled | SUSPENDED |
BLOCKED | BLOCKED | ||
PENDING_TERMINATE | CEASE | ||
TERMINATED | TERMINATED | ||
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 Status | Turkcell contract status | In SMS barred | Out SMS barred | In Calls barred | Out Calls barred | Data barred |
---|---|---|---|---|---|---|
ACTIVE | a | N | N | N | N | N |
SUSPENDED | a | Y (opt.) | Y (opt.) | Y (opt.) | Y (opt.) | Y (opt.) |
TERMINATED | d |
For Satellite terminal status in CMO API used a combination of a Product Contract status and terminal aggregated status in Intelsat:
IoT Hub Status | INTELSAT Product Contract status | INTELSAT Satellite terminal aggregated status |
---|---|---|
CREATED | new (and change actions allowed) | |
PENDING_ACTIVE | new (and change actions are not allowed) | |
ACTIVE | active | online |
SUSPENDED | active | suspended |
SUSPENDED | suspended | |
BLOCKED | active | offline |
PENDING_TERMINATE | cancelation | |
TERMINATED | ended |
Update selected characteristics or attributes of target IoT Product
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
Update value or name of individual custom attributes assigned to a SIM Card.
Delete Custom Attributes
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
Delete invidual custom attributes assigned to a SIM Card.
Batch Update
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✖ | ✔ | ✖ | ✖ | ✔ | ✖ | ✔ | ✖ | ✔ |
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
TMSP | TMUS | INTELSAT | IOTA | JASPER | AIRLINQ | 1NCE | STC | TURKCELL | GALAXY1 |
---|---|---|---|---|---|---|---|---|---|
✔ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ |
For asynchronous operations that were not yet processed it is possible to send an API request to cancel its execution.