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:
- GET -> Return all subscriptions based on Label, Company or customFields search
- 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" } ] }