IOT Cellular Connectivity Management

In the following examples, we'll show you how to use the Internet of Things SIM Management platform REST APIs to manage your IoT M2M SIM cards.

SIM management

  1. Get information for all account related SIM cards
  2. Get information for specific SIM card
  3. Update specific SIM card SIM name
  4. Change specific SIM card status
  5. Get usage information for specific SIM card
  6. Send SMS message to specific SIM card
  7. Run SIM diagnostics
  8. Get usage information for all account-related SIM cards

For getting information for all SIM cards associated with your account you can use the API method. There are only 2 non-mandatory parameters that you can use in this request. A limit parameter that limits the number of SIM cards to be returned per page, if not defined it's set to the default value which is 20 and page parameter which defines page number that is requested, if not set the default value is 1. If limit and page are not defined, API will return only the first 20 SIM cards associated with the account, in order to request the next 20 SIM cards you need to send a request with page parameter set to 2.
 

Resource

GET https://api.infobip.com/iot/2/sims

Property name Type Description
limit integer Page size limit (20 if not defined, max value is 100)
page integer Requested page number (1 if not defined)

Request example:

GET /iot/2/sims HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==	
  

Response: 

200 OK

{ 
  "page": 1,
  "limit": 2,
  "sims": [
      {
          "iccid": "8981100022152967705",
          "status": "Activation Ready",
          "createdAt": "2019-06-04T11:42:49",
          "updatedAt": "2019-06-04T11:42:49",
          "msisdn": "8102001388265",
          "model": {
              "type": "Standard",
              "provisioning": "UICC",
              "size": "Trio (2FF, 3FF, 4FF)"
          }
      },
      {
          "iccid": "8981100022152967721",
          "imsi": "310150123456789",
          "name": "1st activated",
          "status": "Active",
          "createdAt": "2019-06-04T11:42:48",
          "updatedAt": "2019-06-04T11:42:48",
          "msisdn": "8931826018675",
          "serviceProfileId": "44236542",
          "model": {
              "type": "Embedded",
              "grade": "Industrial",
              "provisioning": "UICC",
              "size": "MFF2/QFN8"
          }
      }
  ]
}	
  

Response format:

If successful, the response header HTTP status code will be 200 OK and confirmative response will be returned in the body.

If you try to send a message without authorization, you will get a response with the HTTP status code 401 Unauthorized.

 

Sim Report Response:

Property name Type Description
iccid string Integrated Circuit Card Identifier - SIM cards unique serial number.
imsi string International Mobile Subscriber Identity - uniquely identifies every user of a cellular network.
name string SIM's unique name defined in the system, it helps a customer with its SIM cards identification.
status string Status of the SIM card. Possible statuses are Imported, Activation Ready, Active, Suspended, Deactivated.
createdAt date The date that SIM card was first added to the system, also a date of first provisioning of the SIM card. Has the following format: yyyy-MM-dd'T'HH:mm:ss.
updatedAt date The date that SIM card was last updated, a SIM card name change on customer request, or status change will update this field. Has the following format: yyyy-MM-dd'T'HH:mm:ss.
msisdn string Mobile Station International Subscriber Directory Number - a number used to identify a mobile phone number internationally.
serviceProfileId string Indicates Service Profile which is currently assigned to the SIM card.
model model Indicates a SIM card model.

 

Model:

Property name Type Description
type string Indicates the SIM card type. Possible values are Standard, Embedded or SoftSIM.
grade string Indicates SIM card grade which varies from Industrial, Automotive to others. If left blank the grade is Standard.
provisioning string Indicates SIM card remote provisioning possibility. It can be either UICC or eUICC where the second describes the ability for remote SIM provisioning.
size string Indicates SIM card size or format. Possible values are Trio (2FF, 3FF, 4FF), 2FF, 3FF, 4FF, MFF, MFF2/QFN8, DFN8, DFN6

2. Get information for specific SIM card

For getting information for a specific SIM card associated with your account you can use this API method. There is only 1 mandatory parameter that you need to use in this request. You need to enter the exact ICCID of the SIM card for which you want to request information in the API request path.

Resource

GET https://api.infobip.com/iot/2/sims/{iccid}

Parameters

Property name Type Description
iccid string ICC id of the SIM to return info for

 

Request example:

GET /iot/2/sims/8981100022152967721 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==	
  

Response:

{
    "iccid": "8981100022152967721",
    "imsi": "310150123456789",
    "name": "1st activated",
    "status": "Active",
    "createdAt": "2019-06-04T11:42:48",
    "updatedAt": "2019-06-04T11:42:48",
    "msisdn": "8931826018675",
    "serviceProfileId": "44236542",
    "model": {
        "type": "Embedded",
        "grade": "Industrial",
        "provisioning": "UICC",
        "size": "MFF2/QFN8"
    }
}	
  

Response format:

The response format is the same as for the "Get information for all account-related SIM cards". For more information please check it out there.

3. Update specific SIM card SIM name or status

For updating specific SIM card name you can use this API method. The SIM card you want to update needs to be associated with your account. There are two mandatory parameters that you need to use in this request. You need to enter the exact ICCID of the SIM card for which you want to update in the API request path. In order to change the name of the SIM card, you also need to provide specific SIM name in the request body as shown in the example.

Resource

PATCH https://api.infobip.com/iot/1/sims/{iccid}

Parameters

Property name Type Description
iccid string ICC id of the SIM to update the SIM name
name string New simName to update the SIM card name property with

 

Request example:

PATCH /iot/1/sims/8981100022152967721 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
	"name": "1st SIM card"
}	
  

Response:

200 OK

 
{    
	"actionId": "f597d319-de5c-4524-9378-e95478b58dad"
}	
  

Response format:

If successful, the response header HTTP status code will be 200 OK and confirmative response will be returned in the body. Returned is the “actionId” that was performed on request. This ID can be used for troubleshooting in case of any issues with the action.

If you try to send a message without authorization, you will get a response with the HTTP status code 401 Unauthorized.

4. Change specific SIM card status

For updating specific SIM card status to "Active" or "Suspended" you can use this API method. You will receive SIM card in „activation ready“ status, in order to start using the SIM card you need to first activate it using this API. The SIM card you want to change the status for needs to be associated with your account. There are two mandatory parameters that you need to use in this request. You need to enter the exact ICCID of the SIM card you want to update in the API request path. In order to change the status of the SIM card, you also need to specify the new status in the request body as shown in the request example.

Resource

PUT https://api.infobip.com/iot/1/sims/{iccid}/status

Parameters

Property name Type Description
iccid string ICC id of the SIM to update the status for
status string New status to update SIM card, it can be "Active" or "Suspended" which will result the SIM card to change status accordingly.

 

Request example:

PUT /iot/2/sims/8981100022152967721/status HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
	"status": "Active/Suspended",
}	
  

Response:

200 OK

{    
	"actionId": "f597d319-de5c-4524-9378-e95478b58dad"
}	
  

Response format:

If successful, the response header HTTP status code will be 200 OK and confirmative response will be returned in the body. Returned is the "actionId" that was performed on request. This ID can be used for troubleshooting in case of any issues with the action.

If you try to send a message without authorization, you will get a response with the HTTP status code 401 Unauthorized.

5. Get usage information for specific SIM card

In order to get the usage for the current month for a specific SIM card, you can use this API method. The SIM card you want to get the usage for needs to be associated with your account. There is only one mandatory parameter that you need to use in this request. You need to enter the exact ICCID of the SIM card for which you want to request information in the API request path.

Resource: 

GET https://api.infobip.com/iot/2/sims/{iccid}/usage

Parameters

Property name Type Description
iccid   ICC id of a SIM to get the usage for

 

Request example: 

GET /iot/2/sims/8981100022152967721/usage HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==	
  

Response: 

{
     "iccid": "8981100022152967721",
     "receivedSmsCount": null,
     "sentSmsCount": null,
     "usedDataBytes": 27199488,
     "receivedCallsCount": null,
     "sentCallsCount": null
}	
  

Response format:

If successful, the response header HTTP status code will be 200 OK and confirmative response will be returned in the body.

If you try to send a message without authorization, you will get a response with the HTTP status code 401 Unauthorized.

Sim Usage Report Response:

Property name Type Description
iccid string Integrated Circuit Card Identifier - SIM cards unique serial number.
simName string SIM's unique name defined in the system, it helps a customer with its SIM cards identification.
totalSmsMt string Number of sent SMS MT (mobile terminated) messages from the Infobip system to the SIM card in the observed period.
totalSmsMo string The number of sent SMS MO (mobile originated) from the SIM card in the observed period.
totalData string Amount of data traffic used on the SIM card in the observed period in bytes.
totalVoiceIncoming string Amount of incoming voice traffic to the SIM card in the observed period in seconds.
totalVoiceOutgoing string Amount of outgoing voice traffic from the SIM card in the observed period in seconds.

6. Send SMS message to specific SIM card

In order to send SMS to a specific SIM card, you can use this API method. The SIM card you want to send SMS to needs to be associated with your account. There are only two mandatory parameters that you need to use in this request. You need to enter the exact ICCID of the SIM card for which you want to request information in the API request path. In addition to that, In order to send SMS to the SIM card, you also need to provide text of the SMS message in the request body.

Resource

POST https://api.infobip.com/iot/1/sims/{iccid}/sms

Parameters

Property name Type Description
iccid string ICC id of a SIM to send the SMS message to
text string SMS message text to send to the SIM card, the maximum character set is 160 characters

 

Request example:

POST /iot/1/sims/8981100022152967721/sms HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
	"text": "This is an example of SMS message text."
}	
  

Response:

200 OK

	
  

Response format: 

If successful, the response header HTTP status code will be 200 OK and confirmative response will be returned in the body.

If you try to send a message without authorization, you will get a response with the HTTP status code 401 Unauthorized.

7. Run SIM diagnostics

You can use this API endpoint to run SIM diagnostics in case of a need for troubleshooting. The SIM card you want to run diagnostics for needs to be associated with your account. Using this method, you will initiate re-sync of all services associated with the SIM card. There is only one mandatory parameter that you need to use in this request. You need to enter the exact ICCID of the SIM card in the API request path.

Resource

POST https://api.infobip.com/iot/1/sims/{iccid}/diagnostic

Parameters

Property name Type Description
iccid string ICC id of the SIM to get the usage for

 

Request example:

GET /iot/1/sims/8981100022152967721/diagnostic HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==	
  

Response:

{    
	"actionId": "f597d319-de5c-4524-9378-e95478b58daf"
}	
  

Response format:

If successful, the response header HTTP status code will be 200 OK and confirmative response will be returned in the body. Returned is the "actionId" that was performed on request. This ID can be used for troubleshooting in case of any issues with the action.

If you try to send a message without authorization, you will get a response with the HTTP status code 401 Unauthorized.

In order to get usage for the current month for all SIM cards associated with your account, you can use this API method. There are only 2 non-mandatory parameters that you can use in this request. A limit parameter that limits the number of SIM cards to be returned per page, if not defined it's set to the default value which is 20 and page parameter which defines page number that is requested, if not set the default value is 1. If limit and page are not defined, API will return usage for only first 20 SIM cards associated with the account, in order to request next 20 SIM cards you need to send a request with page parameter set to 2.

Resource

GET https://api.infobip.com/iot/2/sims/usage/monthly

Parameters

Property name Type Description
limit integer Page size limit (20 if not defined, the max value is 100)
page integer Requested page number (1 if not defined)

 

Request example:

GET /iot/2/sims/usage/monthly HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==	
  

Response:

{ 
  "page": 1,
  "limit": 2, 
  "usage": [
     {
     "iccid": "8981100022152967721",
     "receivedSmsCount": null,
     "sentSmsCount": null,
     "usedDataBytes": 27199488,
     "receivedCallsCount": null,
     "sentCallsCount": null
		 },
     {
     "iccid": "8981100022152967705",
     "receivedSmsCount": null,
     "sentSmsCount": null,
     "usedDataBytes": 227199488,
     "receivedCallsCount": null,
     "sentCallsCount": null
		 }
   ]
}	
  

Response format:

If successful, the response header HTTP status code will be 200 OK and confirmative response will be returned in the body..

If you try to send a message without authorization, you will get a response with the HTTP status code 401 Unauthorized.

Sim Usage Report Response:

The response format is the same as for the "Get usage information for specific SIM card". For more information please check it out there.