Legacy | Get Devices List

Tip: A new endpoint is now available for this action. See Get Devices List.
Restriction: The API endpoints in this section are not supported in the public cloud.

Retrieves the list of devices, optionally matching the specified filter parameters.

The list is automatically filtered to only include devices accessible by the user's roles.

Request syntax

Copy
https://mycloud.perfectomobile.com/services/handsets?operation=list&securityToken=value[&optionalParameter=value]

Parameters

Name Type Default Description
securityToken* string

A unique cryptographic key assigned to an authorized user.

admin  boolean false true to filter the list to only show devices that the user is able to administrate and provide administrative information in the response.
deviceId  string 
The identifier of the device specified as IMEI or ESN. 
manufacturer  string 
The manufacturer of the device. For example: Apple, Samsung, HTC, ... 
model  string 
The model of the device. For example: Galaxy S6, iPhone 6, ... 
distributor  string 
The distributor of the device. 
firmware  string 
The version of the firmware of the device. 
operator.name  string 
The name of the operator network to which the device is connected. 
operator.country  string 
The country in which the operator is located. 
operator.code  string 
The code associated with the operator. 
description  string 
The description of the device. 
location  string 
The geographical location of the device. 
language  string 
The current language of the device. 
status  string 
The current connectivity status of the device. The following is a list of the possible values: 
disconnected connected unavailable - This status indicates a device that is connected but is not available. For example, the device might be initializing or may have encountered an error.
allocatedTo  string 
The identifier of the user account that is currently using the device. 
reservedTo  string 
The identifier of the user account that is currently reserving the device. 
availableTo  string 
The identifier of the user account for which the device is currently available. 
owner  string 
The owner user id. Used by an administrator to list all the devices which are accessible to this owner. This accessibility is determined by the user's roles - the user can access only devices that have one of the roles assigned to him. 
inUse  boolean
true indicates that the device is currently in use.
cradleId  string 
The identifier of the cradle to which the device is connected. 
os  string 
The name of the device's operating system. 
osVersion  string 
The version of the device's operating system. 
resolution  string 
The resolution of the device's screen. 
phoneNumber  string 
The phone number of the device. 
dynamicField.<name> string 
The name and value of one or more a dynamic fields for the device, each prefixed with dynamicField.. For example, to specify an integer dynamic field called timeout with the value 10, add dynamicField.timeout=10 to the URL.
link.type  string 
The type of device. The possible values are: all, local or lab. 

* Mandatory parameter

The parameters above support Regular Expressions apart from the status, user, password, owner, availableTo, and link.type.

Response

The response is the list of devices in XML format. The header of the response indicates the number of handsets. Each handset reported includes the information described in Get Device Information.

Copy

Handset list format

<handsets modelVersion="<modelVersion>" time="<time>" items="<noOfItems>">    <handset>        ...
    </handset><!--repeat according to "items" value--></handsets>

Examples

The following shows some of the possible requests for getting the information of one or more devices using different filters.

Copy

Request

//all connected devices 
https://mycloud.perfectomobile.com/services/handsets?operation=list&securityToken=value&status=connected 
//all connected Apple iphone devices 
https://mycloud.perfectomobile.com/services/handsets?operation=list&securityToken=value&status=connected&manufacturer=Apple&model=iPhone-4S 
//all connected Apple or Samsung devices 
https://mycloud.perfectomobile.com/services/handsets?operation=list&securityToken=value&status=connected&manufacturer=Apple|Samsung 
//all connected devices allocated to users from mydomain.com 
https://mycloud.perfectomobile.com/services/handsets?operation=list&securityToken=value&allocatedTo=.*@mydomain.com