APIs CMO API SIM card activation

This tutorial will guide you on activating a SIM card and verifying its activation status with the Connection Management Orchestrator (CMO) APIs. We’ll cover both synchronous and asynchronous methods in detail.

Synchronous request - In the API, calls for operations like activating a SIM card happen immediately. The client application sends the request and waits for an immediate response. Asynchronous request - In the API, calls for operations like activating a SIM card receive a tracker ID. This tracker ID allows the user to track the operation’s progress while being processed in the background.

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
  • Update the status of an IoT Connection Product (Synchronous)
  • Update the status of an IoT Connection Product (Asynchronous)
  • Monitor the result of an asynchronous status change (Asynchronous)

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>"

curl --location "$API_URL/$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-89490200001640018498",
      "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 status of that SIM card.

  • Retrieve the details of an IoT Connection Product with the following cURL command and replace the value <your_product_id> with your data.
  • Copy & paste
  • Example
  • Output
PRODUCT_ID="<your_product_id>"
# 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/$TENANT/product/$PRODUCT_ID" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN"

PRODUCT_ID="JASPER-899xxxxxxxxxxxxxxx47"
# 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/eos/product/$PRODUCT_ID" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
        "id": "JASPER-899xxxxxxxxxxxxxxx47",
        "href": "<api_url>/TENANT/product/JASPER-899xxxxxxxxxxxxxxx47",
        "isBundle": true,
        "startDate": "2020-04-01T20:00:00.000Z",
        "status": "INACTIVE",
        "connectivityType": "CELLULAR",
        "relatedParty": [
            {
                "id": "100125",
                "name": "JASPER_1",
                "role": "customer"
            }
        ],
        "productOffering": {
            "name": "1GB Shared Fixed Pool Roaming"
        },
        "productCharacteristic": [
            {
                "name": "SYSTEM",
                "value": "JASPER"
            }
        ],
        "productRelationship": [
            {
                "type": "BUNDLED",
                "product": {         
                    "id": "JASPER-899xxxxxxxxxxxxx747-simCard",
                    "href": "<api_url>/TENANT/product/JASPER-899xxxxxxxxxxxxx747-simCard",
                    "isBundle": false,
                    "status": "ACTIVE",
                    "productCharacteristic": [
                        {
                            "name": "dateActivated",
                            "value": "2020-05-20T14:24:49.697Z"
                        },
                        {
                            "name": "dateAdded",
                            "value": "2020-04-02T07:17:45.375Z"
                        },
                        {
                            "name": "dateUpdated",
                            "value": "2023-06-13T03:36:35.783Z"
                        },
                        {
                            "name": "euiccid",
                            "value": ""
                        },
                        {
                            "name": "globalSimType",
                            "value": ""
                        },
                        {
                            "name": "ICCID",
                            "value": "899xxxxxxxxxxxxx747"
                        },
                        {
                            "name": "imei",
                            "value": "358xxxxxxxxxxx01"
                        },
                        {
                            "name": "IMSI",
                            "value": "42xxxxxxxxxxx61"
                        },
                        {
                            "name": "MSISDN",
                            "value": "97xxxxxxxx27"
                        },
                        {
                            "name": "simNotes",
                            "value": ""
                        }
                    ],
                    "customProperty": [],
                    "@baseType": "product",
                    "@type": "simCard"
                }
            },
            }
        ],
        "@baseType": "product",
        "@type": "IoTConnection",
        "correlationId": "e11d3bcb-98a7-45a4-b1b8-7c475b9b073b"
    }
  • 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. Update the status of an IoT Connection Product (Synchronous)

After checking if the status of the SIM card you want to activate is deactivated, proceed with the request to activate it using the id number retrieved earlier in the tutorial.

  • Update the status of the IoT Connection Product using a payload with the following cURL command
NOTE
  • op = the operation you would like to execute
  • path = the attribute you wish to change
  • value = the value you wish to change
  • Copy & paste
  • Output
# 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 --request PATCH "$API_URL/$TENANT/product/${PRODUCT_ID}-simCard" \
  --header 'Content-Type: application/json-patch+json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN"  \
  --data '[
    {
    "op": "replace",
    "path": "/status",
    "value": "ACTIVE"
    }
]'

{
        "id": "JASPER-899xxxxxxxxxxxxxxx47-simCard",
        "href": "<api_url>/eos/product/JASPER-899xxxxxxxxxxxxxxx47-simCard",
        "isBundle": false,
        "status": "ACTIVE",
        "productCharacteristic": [
            {
                "name": "dateActivated",
                "value": "2020-05-20T14:24:49.697Z"
            },
            {
                "name": "dateAdded",
                "value": "2020-04-02T07:17:45.375Z"
            },
            {
                "name": "dateUpdated",
                "value": "2023-06-13T12:43:16.519Z"
            },
            {
                "name": "euiccid",
                "value": ""
            },
            {
                "name": "globalSimType",
                "value": ""
            },
            {
                "name": "ICCID",
                "value": "899xxxxxxxxxxxxxxx47"
            },
            {
                "name": "imei",
                "value": "358xxxxxxxxxx01"
            },
            {
                "name": "IMSI",
                "value": "424xxxxxxxx961"
            },
            {
                "name": "MSISDN",
                "value": "971xxxxxxxx627"
            },
            {
                "name": "simNotes",
                "value": ""
            }
        ],
        "customProperty": [],
        "@baseType": "product",
        "@type": "simCard",
        "correlationId": "23860f1e-d042-448a-91b4-335a90fbd554"
    }
  • You have to append to -simCard at the end of the request path because there are multiple substructures inside a connectivity product. -dataConnectivity is another example of a request path.
  • To check if the status is successfully activated, use the same cURL command we used to Retrieve details of an IoT Product and check if the SIM card status has changed from DEACTIVATED to ACTIVE.
# 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/$TENANT/product/$PRODUCT_ID" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN"
  • This change will also reflect in the GUI of the T IoT Hub. To view the SIM card status, visit the Connectivity Management page.

Step 4. Update the status of an IoT Connection Product (Asynchronous)

If you work with a system that operates asynchronously, you will utilize the same cURL command used to update the status. However, you will also receive a tracker ID number to monitor the progress of your request.

  • Perform the same action we used earlier to update the status of the IoT Connection Product using a payload with the following cURL command
# 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 --request PATCH --location "$API_URL/$TENANT/product/${PRODUCT_ID}-simCard" \
  --header 'Content-Type: application/json-patch+json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data '[
    {
        "op": "replace",
        "path": "/status",
        "value": "ACTIVE"
      }
    ]'
  • If your system operates asynchronously, your output should provide you with a monitor link that we will use in the next step:
<api_url/$TENANT/monitor/89xxxxxxxxxxxxxxxx60-168xxxxxxx707>

Step 5. Monitor the result of the asynchronous status change (Asynchronous)

Use the monitor link received in the previous step to track the request progress. To do this, interact with the monitor operation, which is a part of the CMO API.

  • Send a monitor request with the monitor link id, which are the numbers after the monitor/… in the URL with the following cURL command
  • Copy & paste
  • Output
MONITOR_ID=<your_monitor_id>
# 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/$TENANT/monitor/$MONITOR_ID" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
    "sourceHref": "<api_url>/eos/pdocut/TMSP-89xxxxxxxxxxxxxxxx60-168xxxxxxx707-simCard",
    "state": "InProgress"
}
  • In the monitor output, you can see details about your operation and the operation response.
  • At the bottom of the body, you have a state which tells you the status of the operation. It will look something like this:
NOTE
  • Depending on your system’s setup, update time may vary.
  • To check if the status is successfully activated, use the same cURL command we used to Retrieve details of an IoT Product and check if the SIM card status has changed from DEACTIVATED to ACTIVE.
# 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/$TENANT/product/$PRODUCT_ID" \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header "Authorization: Bearer $ACCESS_TOKEN"