Get Device Usage

Description

Returns cycle-to-date usage information for a specified device.

Resource URL

GET rws/api/v{apiVersion}/devices/{iccid}/ctdUsages

Request Parameters

Reqeust Parameter and Description
Parameter Description
apiVersion

The version number for this API. The current version for all functions is 1.

iccid The ICCID of the device you want information about.

Response Parameters

Return Values and Descriptions
Return Value Description
iccid The ICCID of the device.
imsi The device IMSI.
msisdn The device MSISDN or phone number.
imei The device IMEI.
status The device SIM status. For a list of valid values, see SIM Status Values.
ratePlan The name of the rate plan associated with the device.
communicationPlan The name of the communication plan associated with the device.
ctdDataUsage

The amount of data used (in bytes) since the beginning of the billing cycle.

ctdSMSUsage

A count of the mobile-originated and mobile-terminated messages since the beginning of the billing cycle.

ctdVoiceUsage

The number of voice seconds used since the beginning of the billing cycle.

ctdSessionCount The number of data sessions since the beginning of the billing cycle.
overageLimitReached A true/false value indicating whether the device has reached the data limit set in the rate plan.
overageLimitOverride

Indicates whether the device can exceed the data limit specified in the rate plan. The possible values are:

•  DEFAULT. The device cannot exceed the data limit.

•  TEMPORARY_OVERRIDE. The device can use any amount of data until the end of the current billing cycle, at which point Control Center will begin enforcing the data limit set in the rate plan.

•  PERMANENT_OVERRIDE. The device can use any amount of data, regardless of the data limit defined in the rate plan.

Request Example

Make sure to use your own user credentials. See Authentication for information about creating an authorization header.

json
Copycurl -X GET --header "Accept: application/json" --header "Authorization: Basic <YOUR-ENCRYPTED-CREDENTIALS>" "https://rws-jpotest.jasper.com/rws/api/v1/devices/8988216716970004975/ctdUsages"

Response Example

json
Copy{
	"iccid": "8988216716970004975",
	"imsi": "901161697004975",
	"msisdn": "882351697004975",
	"imei": "",
	"status": "ACTIVATED",
	"ratePlan": "hphlr rp1",
	"communicationPlan": "CP_Basic_ON",
	"ctdDataUsage": 0,
	"ctdSMSUsage": 0,
	"ctdVoiceUsage": 0,
	"ctdSessionCount": null,
	"overageLimitReached": false,
	"overageLimitOverride": "DEFAULT"
}

Code Samples

Make sure to use the Control Center sandbox URL and your own user credentials.

python
javascript
ruby
Copyimport requests 
import json 
import base64 
import pprint 

cobrandURL=input("Cobrand URL: ")											
url = 'https://'+cobrandURL+'/rws/api/v1/devices/'+input("iccid: ")+'/ctdUsages' 
myResponse = requests.get(url,auth=(input("username: "),input("api_key: "))) 
# For successful API call, response code will be 200 (OK) 
if(myResponse.ok): 
	# Loading the response data into a dict variable 
	# json.loads takes in only binary or string variables so using content to fetch binary content
    # Loads (Load String) takes a Json file and converts into python data structure (dict or list, depending on JSON) 
    jData = json.loads(myResponse.content)
	pp=pprint.PrettyPrinter(indent=4) 
	pp.pprint(jData) 
else: 
    # If response code is not ok (200), print the resulting http error code with description 
    print("Failure")
	myResponse.raise_for_status()
Copyvar request = require('request');
var body = [];
request.get('https://<your-base-URL>/rws/api/v1/devices/8988216716970004975/ctdUsages').auth('username', 'password', false)
    .on('error', function(error){
        console.log('Error:', error);
    })
    .on('response', function(response) {
        console.log(response.statusCode); // return statusCode
        console.log(response.headers['content-type']); // return contentType
    })
    .on('data',function(chunk){
        body.push(chunk);
    })
    .on('end',function(){
        body = Buffer.concat(body).toString();
        console.log(body);
    });
Copy#!/usr/bin/ruby -w
require 'rest-client'
require 'json'
  
url = 'https://<your-base-URL>/rws/api/v1/devices/89011704252318147060/ctdUsages'
response = RestClient::Request.execute(
 method: :get,
 url: url,
 user: 'username',
 password: 'password',
 :headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error Codes, HTTP Codes, and Descriptions
Error Code HTTP Code Error Message
10000001 401

Invalid credentials.

Description: Control Center uses this error message when the API credentials are invalid or when the IP address is not within the allowed range.

10000024 400 Invalid apiVersion.
10000031 400 Invalid Zone.
20000001 404 Resource not found - Invalid ICCID.
30000001 500 Unknown server error.