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