APIs CMO API Viewing Consumption Data

This tutorial will guide you on viewing consumption data using the Connection Management Orchestrator (CMO) APIs. We’ll focus on the synchronous method, as this is the only available option for viewing consumption data.

Synchronous Data Viewing - In the API, calls for operations like viewing consumption data happen immediately. The client application sends the request and waits for an immediate response, which provides the latest consumption data. This direct method ensures real-time access to data usage statistics.

Currently, only the TMSP provider supports both cellular and satellite levels for consumption data viewing.

NOTE
  • The API Access Token has an expiration time of 300 seconds (5 minutes).
  • If you get error 401 when trying to make a request this is most likely an expired token.

You will learn how to

  • Retrieve a list of IoT Connection Products
  • Retrieve details of an IoT Connection Product
  • Retrieve details of an Usage Volume Product (Data)

Prerequisites

Before we begin, ensure you complete the initial tutorial, “Connecting Your Application to the T IoT Hub”.

Make sure that you:

  1. Register your application in Application Access Management
  2. Configure a request to fetch the API access token
  3. Possess an HTTP Client, such as Postman or cURL .
NOTE
  • This tutorial will refer to the use of cURL. If you use a different platform, the setup might vary.

Step 1. Retrieve a list of IoT Connectivity Products

To identify connectivity products that need updating, you need to obtain a list of these products. In our case, we will be using cURL to execute operations. To check if cURL is installed on your hardware, open a terminal or CMD and run:

  • Copy & paste
  • Output
TENANT="<your_tenant_name>"
ACCESS_TOKEN="<access_token>"
# Replace <api_url> below with the API URL (click chain icon next to API version in Application Management UI to copy it to clipboard)
API_URL="<api_url>"

fields=id,connectivityType&pageNumber=1&pageSize=15
curl --location "$API_URL/connection-management-orchestrator/v5/$TENANT/product?fields=id,connectivityType,status&pageNumber=1&pageSize=10" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
  "entities": [
    {
      "id": "JASPER-899xxxxxxxxxxxxxxx47",
      "connectivityType": "CELLULAR",
      "status": "INACTIVE"
    },
    {
      "id": "JASPER-899xxxxxxxxxxxxxxx46",
      "connectivityType": "CELLULAR",
      "status": "SUSPENDED"
    },
    {
      "id": "JASPER-899xxxxxxxxxxxxxxx45",
      "connectivityType": "CELLULAR",
      "status": "ACTIVE"
    },
    {
      "id": "TMSP-894xxxxxxxxxxxxxxx72",
      "connectivityType": "CELLULAR",
      "status": "PENDING_ACTIVE"
    },
    {
      "id": "TMSP-894xxxxxxxxxxxxxxx80",
      "connectivityType": "CELLULAR",
      "status": "ACTIVE"
    },
    {
      "id": "TMSP-894xxxxxxxxxxxxxxx98",
      "connectivityType": "CELLULAR",
      "status": "BLOCKED"
    },
    {
      "id": "INTELSAT-2xxxxxx2",
      "connectivityType": "SATELLITE",
      "status": "INACTIVE"
    }
   ...
  ]
  ...
}
NOTE
  • The pageSize refers to the number of Connectivity products you wish to retrieve from the first page. In this case, we are retrieving ten products. You can also use pageNumber to refer to a specific page. Play around with the pageSize number to retrieve more or fewer products.

Step 2. Retrieve details of an IoT Connection Product

Now you have identified the connection product that you wish to work with. Retrieve the details of this product by using the id number to view the whole data about this product including the usage volume of that SIM card.

  • Retrieve the details of an IoT Connection Product with the following cURL command and replace the value <your_product_id> and your_tenant_name with your data.
  • Copy & paste
  • Example
  • Output
PRODUCT_ID="<your_product_id>"
TENANT="<your_tenant_name>"
# Replace <api_url> below with the API URL (click chain icon next to API version in Application Management UI to copy it to clipboard)
API_URL="<api_url>"

curl --location "$API_URL/connection-management-orchestrator/v5/$TENANT/product/$PRODUCT_ID" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN"

PRODUCT_ID="TMSP-894xxxxxxxxxxxxxxx80"
TENANT="tmsp_tenant"
# Replace <api_url> below with the API URL (click chain icon next to API version in Application Management UI to copy it to clipboard)
API_URL="<api_url>"

curl --location "$API_URL/connection-management-orchestrator/v5/$TENANT/product/$PRODUCT_ID" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": "TMSP-894xxxxxxxxxxxxxxx80",
  "href": "https://api.telekom.de/t-iot-hub/connection-management-orchestrator/v5/tmsp_tenant/product/TMSP-894xxxxxxxxxxxxxxx80",
  "isBundle": true,
  "startDate": "2020-04-01T20:00:00.000Z",
  "status": "ACTIVE",
  "connectivityType": "CELLULAR",
  "relatedParty": [
    {
      "id": "10347",
      "name": "Ref 10347",
      "role": "customer"
    }
  ],
  "productOffering": {
    "name": "3600236701"
  },
  "productCharacteristic": [
    {
      "name": "SYSTEM",
      "value": "TMSP"
    }
  ],
  "productRelationship": [
    {
      "type": "BUNDLED",
      "product": {
        "id": "TMSP-894xxxxxxxxxxxxxxx80-simCard",
        "href": "https://api.telekom.de/t-iot-hub/connection-management-orchestrator/v5/tmsp_tenant/product/TMSP-894xxxxxxxxxxxxxxx80-simCard",
        "isBundle": false,
        "status": "ACTIVE",
        "productCharacteristic": [
          {
            "name": "accessProfile",
            "value": "22xxxxxx80"
          },
          {
            "name": "barringProfile",
            "value": ""
          },
          {
            "name": "busyState",
            "value": "0"
          },
          {
            "name": "costLimitProfile",
            "value": ""
          },
          {
            "name": "euiccid",
            "value": "222xxxxxxxxxxxx02"
          },
          {
            "name": "fraudProfile",
            "value": ""
          },
          {
            "name": "fraudStatus",
            "value": "No profile"
          },
          {
            "name": "limitProfile",
            "value": ""
          },
          {
            "name": "limitStatus",
            "value": "No profile"
          },
          {
            "name": "ICCID",
            "value": "894xxxxxxxxxxxxxxx80"
          },
          {
            "name": "IMSI",
            "value": "26xxxxxxxxxxx88"
          },
          {
            "name": "MSISDN",
            "value": "49xxxxxxxx17"
          },
          {
            "name": "restrictionStatus",
            "value": "none"
          },
          {
            "name": "smsrid",
            "value": "66633312345100002"
          }
        ],
        "customProperty": [],
        "@baseType": "product",
        "@type": "simCard"
      }
    },
    {
      "type": "BUNDLED",
      "product": {
        "id": "TMSP-894xxxxxxxxxxxxxxx80-dataConnectivity",
        "href": "https://api.telekom.de/t-iot-hub/connection-management-orchestrator/v5/tmsp_tenant/product/TMSP-894xxxxxxxxxxxxxxx80-dataConnectivity",
        "isBundle": false,
        "productCharacteristic": [
          {
            "name": "apn_1",
            "value": "tmsp.apn.de"
          },
          {
            "name": "country",
            "value": "DE"
          },
          {
            "name": "imei",
            "value": "23xxxxxxxxxx83"
          },
          {
            "name": "mcc",
            "value": ""
          },
          {
            "name": "mnc",
            "value": ""
          },
          {
            "name": "networkProvider",
            "value": ""
          },
          {
            "name": "pdpType",
            "value": ""
          },
          {
            "name": "ratType",
            "value": ""
          },
          {
            "name": "type",
            "value": ""
          }
        ],
        "@baseType": "product",
        "@type": "dataConnectivity"
      }
    },
    {
      "type": "BUNDLED",
      "product": {
        "id": "TMSP-894xxxxxxxxxxxxxxx80-usageVolume-data",
        "href": "https://api.telekom.de/t-iot-hub/connection-management-orchestrator/v5/tmsp_tenant/product/TMSP-894xxxxxxxxxxxxxxx80-usageVolume-data",
        "isBundle": false,
        "usageType": "DATA",
        "bucketCounter": [
          {
            "level": "global",
            "valueName": "9800 KB",
            "value": {
              "amount": "9800",
              "units": "KB"
            },
            "consumptionPeriod": {
              "startDateTime": "2020-04-01T20:00:00Z",
              "endDateTime": "2024-03-23T10:44:48.995Z"
            },
            "counterType": "USED"
          },
          {
            "level": "cellular",
            "valueName": "8300 KB",
            "value": {
              "amount": "8300",
              "units": "KB"
            },
            "consumptionPeriod": {
              "startDateTime": "2020-04-01T20:00:00Z",
              "endDateTime": "2024-03-23T10:44:48.995Z"
            },
            "counterType": "USED"
          },
          {
            "level": "satellite",
            "valueName": "1500 KB",
            "value": {
              "amount": "1500",
              "units": "KB"
            },
            "consumptionPeriod": {
              "startDateTime": "2020-04-01T20:00:00Z",
              "endDateTime": "2024-03-23T10:44:48.995Z"
            },
            "counterType": "USED"
          }
        ],
        "@baseType": "product",
        "@type": "usageVolume"
      }
    }
  ],
  "@baseType": "product",
  "@type": "IoTConnection",
  "errors": [],
  "correlationId": "3843sda6-as3u-384n-mu37-dj27has4hd"
}
  • One of the benefits of using the API is you can retrieve a much more detailed view of your connection products compared to the user interface of the T IoT Hub.

Step 3. Retrieve details of an Usage Volume Product (Data)

Now you have identified the usage volume product that you wish to work with. Retrieve the details of this product by using the usage volume id to view the whole data about this usage volume product of that SIM card.

  • Retrieve the details of an Usage Volume Product with the following cURL command and replace the value <your_product_id> and your_tenant_name with your data.
  • Copy & paste
  • Output
PRODUCT_ID="TMSP-894xxxxxxxxxxxxxxx80-usageVolume-data"
TENANT="tmsp_tenant"
# Replace <api_url> below with the API URL (click chain icon next to API version in Application Management UI to copy it to clipboard)
API_URL="<api_url>"

curl --location "$API_URL/connection-management-orchestrator/v5/$TENANT/product/$PRODUCT_ID" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": "TMSP-894xxxxxxxxxxxxxxx80-usageVolume-data",
  "href": "https://api.telekom.de/t-iot-hub/connection-management-orchestrator/v5/tmsp_tenant/product/TMSP-894xxxxxxxxxxxxxxx80-usageVolume-data",
  "isBundle": false,
  "usageType": "DATA",
  "bucketCounter": [
    {
      "level": "global",
      "valueName": "9800 KB",
      "value": {
        "amount": "9800",
        "units": "KB"
      },
      "consumptionPeriod": {
        "startDateTime": "2020-04-01T20:00:00Z",
        "endDateTime": "2024-03-23T10:44:48.995Z"
      },
      "counterType": "USED"
    },
    {
      "level": "cellular",
      "valueName": "8300 KB",
      "value": {
        "amount": "8300",
        "units": "KB"
      },
      "consumptionPeriod": {
        "startDateTime": "2020-04-01T20:00:00Z",
        "endDateTime": "2024-03-23T10:44:48.995Z"
      },
      "counterType": "USED"
    },
    {
      "level": "satellite",
      "valueName": "1500 KB",
      "value": {
        "amount": "1500",
        "units": "KB"
      },
      "consumptionPeriod": {
        "startDateTime": "2020-04-01T20:00:00Z",
        "endDateTime": "2024-03-23T10:44:48.995Z"
      },
      "counterType": "USED"
    }
  ],
  "@baseType": "product",
  "@type": "usageVolume",
  "correlationId": "u2nh272hnh-nbya-837h-na63-2u7su927h"
}