Skip navigation
IoT Accelerator Developer Portal
Home Learn Tutorials API: search subscription details
In this section

API: search subscription details

In the new Search Subscription Details API Group are available two new APIs to get the subscription details using GET or POST methods.

The main differences are about the responses:

  1. GET -> Return all subscriptions based on Label, Company or customFields search
  2. POST -> Return all subscritions based on identifierValues filled in the json body of the request

This examples provides the step-by-step description on how to get subscription details using API GET and POST via cURL commands. 

The tutorial is composed of 3 main steps: 

1. Login to retrieve the Bearer Token
2. Getting subscription details for all the SIMs associated to a given company using GET method
3. Getting subscription details for a single SIM using POST method

Sequence of operations

1. Login to retrieve the Bearer Token

Retrieve the auth-token using the POST /​

REQUEST
curl --location --request POST 'https://<IoTA-URL>/iot/api/auth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=cm-public-api-client' \
--data-urlencode 'username=<USERNAME>' \
--data-urlencode 'password=<PASSWORD>'
RESPONSE
{
"access_token": "<TOKEN>",
"token_type": "JWT",
"expires_in": 1800
}

2. Getting subscription details for all the SIMs associated to a given company

Retrieve subscription details for all the SIMs associated to a given company using the GET /iot/api/subscriptions/details?q=company==<COMPANY-ID>

The key is set as "company" but it is possibile to use label or customField instead.

REQUEST
curl --location --request GET 'https://<IoTA-URL>/iot/api/subscriptions/details?q=company==<COMPANY-ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <TOKEN>'
RESPONSE
{
    "subscriptions": [
        {
            "enterprise": "",
            "iccid": "89XXXXXXXXXXXXXXXXXX",
            "detectedImei": "35XXXXXXXXXXXXX",
            "imsi": "2XXXXXXXXXXXXXX",
            "msisdn": "4XXXXXXXXXXXXXX",
            "organizationId": "0.23.103.147",
            "state": "TERMINATED"
        },
        {
            "enterprise": "",
            "iccid": "89XXXXXXXXXXXXXXXXXX",
            "detectedImei": "35XXXXXXXXXXXXX",
            "imsi": "2XXXXXXXXXXXXXX",
            "msisdn": "4XXXXXXXXXXXXXX",
            "state": "ACTIVE_NO_BILLING"
        }
    ],
    "size": 2
}

3. Getting subscription details for a single SIM using POST method

Getting subscription details for a single SIM using POST /iot/api/subscriptions/details and providing within the body request the IMSI of the given SIM.

It is possible require more than one SIM adding multiple comma separated IMSIs inside identifierValues array.

It is possible add more fields in the response adding the parameter additionalFields in query string, in the example LABEL and COSTOM FIELD are required too, the additional fields will be present in the response only if available.

REQUEST
curl --location --request POST 'https://<IoTA-URL>/iot/api/subscriptions/details?additionalFields=LABEL&additionalFields=CUSTOM_FIELDS' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: <Bearer-Token>' \
--data-raw '{
"identifierType": "IMSI",
"identifierValues": [
"2XXXXXXXXXXXXXX"
]
}'
RESPONSE
{
    "subscriptions": [
        {
            "enterprise": "2XXXXXXX",
            "label": "here is my label",
            "iccid": "89XXXXXXXXXXXXXXXXXX",
            "imsi": "2XXXXXXXXXXXXXX",
            "msisdn": "4XXXXXXXXXXXXXX",
            "organizationId": "0.23.103.147",
            "state": "ACTIVE_NO_BILLING"
        }
    ]
}