Search Devices

Description

For a given enterprise account, returns a list of devices that have changed since a specified date. You can filter the list by SIM status.

Resource URL

GET rws/api/v{apiVersion}/devices

Request Parameters

Request Parameters and Descriptions
Parameter Description
apiVersion

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

accountId

(Optional) Unique identifier for the account that owns the devices you're searching for. If you omit this parameter, Control Center uses the account associated with the user name.

modifiedSince A date and time using the ISO 8601 format. The function returns any devices that have been modified since this time.
status (Optional) A SIM status value. The function returns only devices with this status. For a list of valid values, see SIM Status Values.
pageSize

(Optional) Specifies the number of records returned in each response page. The maximum value is 50. The value defaults to 50. See Pagination.

pageNumber

(Optional) Specifies the number of response pages to return. This value defaults to 1. See Pagination.

Response Parameters

The function returns an array of devices with the information below. Records are sorted by modification date in ascending order with the oldest device change listed first.

Return Values and Descriptions
Return Value Description
devices The array containing the device list.
iccid The ICCID of the device.
status The device's 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.

pageNumber

An integer specifying the number of the current response page.

lastPage

A true or false value indicating whether the current response page is the last in the series.

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?accountId=100020620&modifiedSince=2016-04-18T17%3A31%3A34%2B00%3A00&pageSize=50&pageNumber=1"

Response Example

json
Copy{
    "pageNumber": 1,
    "devices": [
        {
            "iccid": "8988216716970004971",
            "status": "ACTIVATION_READY",
            "ratePlan": "hphlr rp1",
            "communicationPlan": "CP_Basic_ON",
        },
        {
            "iccid": "8988216716970004975",
            "status": "ACTIVATED",
            "ratePlan": "hphlr rp1",
            "communicationPlan": "CP_Basic_ON",
        }
    ],
    "lastPage": true
}

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/?modifiedSince=2016-04-18T17%3A31%3A34%2B00%3A00' 
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
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/?modifiedSince=2016-04-18T17%3A31%3A34%2B00%3A00').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/?modifiedSince=2016-04-18T17%3A31%3A34%2B00%3A00'
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.

10000002 400 AccoundId is required.
10000003 400 ModifiedSince is required.
10000004 400 Invalid accountId.
10000005 400 Invalid status.
10000006 400 Invalid pageSize.
10000007 400 Invalid pageNumber.
10000012 400 Invalid date format.
10000024 400 Invalid apiVersion.
30000001 500 Unknown server error.