Get Devices List

Restriction: This API endpoint is 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.

URL	Copy `https://<your_cloud>.app.perfectomobile.com/api/v1/device-management/devices`
Method	`POST`

Header parameters

Name	Description
`Perfecto-Authorization`	The Perfecto security token. For more information, see Generate a security token.

Request parameters

Name	Type	Default	Description
`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 repsonse.

Request body

Name	Type	Description
`deviceId`	string	The identifier of the device specified as IMEI or ESN.
`manufacturer`	string	The manufacturer of the device. For example: Apple, Samsung, HTC, and so on
`model`	string	The model of the device. For example: Galaxy S6, iPhone 6, and so on
`distributor`	string	The distributor of the device.
`firmware`	string	The version of the firmware of the device.
`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` (Indicates a device that is connected but 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's user id. Used by an administrator to list all devices accessible to this owner. Accessibility is determined by the user's roles. A user can access only devices that have one of the roles assigned to the user.
`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 screen.
`phoneNumber`	string	The phone number of the device.
`linkType`	string	The type of device. The possible values are: all, local, or lab
`customFields`	array	The name and value of one or more dynamic fields for the device, in the following format: Copy `{ "name": "fieldName", "value": "value", "category": "DYNAMIC_FIELDS" }` The following category values are allowed: DEVICE_TAGS, DYNAMIC_FIELDS, ADMIN_FIELDS For example, to specify an integer dynamic field called timeout with the value 10, specify: `dynamicField.timeout=10` Copy `{ "customFields": [ { "name": "timeout", "value": "10", "category": "DYNAMIC_FIELDS" } ] }`
`operator`	object	The name of the operator network to which the device is connected, the country in which the operator is located, and the code that is associated with the operator, in the following format: Copy `{ "name": "nameOfOperator", "country": "country", "code": "code" }` Following are relevant examples. Copy Name `{ "operator": { "name": "Etisalat" } }` Copy Country `{ "operator": { "country": "Afghanistan" } }` Copy Code `{ "operator": { "code": "41250" } }` Copy All in one `{ "operator": { "country": "Afghanistan", "name": "Etisalat", "code": "41250" } }`

Restriction: All parameters support Regular Expressions except for status, owner, availableTo, and linkType.

Request body

Following are several examples of the request body. It is mandatory to send all parameters inside the device object. An empty device object is allowed.

Copy

Fetch all devices

{
    "device": {        
    }
}

Copy

Fetch devices on the basis of deviceId

{
    "device": {
        "deviceId": "deviceIdValue"
    }
}

Copy

Fetch devices on the basis of manufacturer

{
    "device": {
        "manufacturer": "Apple|Samsung"
    }
}

Copy

Fetch devices allocatedTo users @myDomain.com

{
    "device": {
        "allocatedTo": ".*@myDomain.com"
    }
}

Copy

Fetch devices on the basis of dynamic fields

{
    "device": {
        "customFields": [{
            "name": "test_field_1",
            "value": "test_value_1",
            "category": "DYNAMIC_FIELDS"
        }]
    }
}

Copy

Fetch devices on the basis of country

{
    "device": {
        "operator": {
            "country": "Afghanistan"
        }
    }
}

Success response

Code: 200 OK

Success response format if admin value = false

Copy

{
    "handsets": {
        "timeStamp": 1677732737205,
        "productVersion": "master",
        "modelVersion": "2.21.0.0",
        "handset": [
            {
                "osBuild": "<<OS_BUILD_VALUE>>",
                "link": {
                    "type": "<<LINK_TYPE_VALUE>>"
                },
                "available": false|true,
                "description": "<<DESCRIPTION>>",
                "language": "<<LANGUAGE>>",
                "imsi": "<<IMSI>>",
                "deviceId": "<<DEVICE_ID>>",
                "resolution": "<<RESOLUTION>>",
                "operator": {
                    "country": "<<COUNTRY>>",
                    "code": "<<CODE>>",
                    "name": "<<NAME>>"
                },
                "manufacturer": "<<MANUFACTURER_VALUE>>",
                "wifiMacAddress": "<<WIFI_MAC_ADDRESS_VALUE>>",
                "mode": "<<MODE_VALUE>>",
                "osVersion": "<<OS_VERSION>>",
                "model": "<<MODEL_VALUE>>",
                "firmware": "<<FIRMWARE_VALUE>>",
                "os": "<<OS_VALUE>>",
                "cpuArch": "<<CPU_ARCH_VALUE>>",
                "originalDeviceId": "<<ORIGINAL_DEVICE_ID>>",
                "phoneNumber": "<<PHONE_NUMBER>>",
                "lastCradleId": "<<LAST_CRADLE_ID>>",
                "reserved": false|true,
                "location": "<<LOCATION_VALUE>>",
                "distributer": "<<DISTRIBUTOR_VALUE>>",
                "nativeImei": "<<NATIVE_IMEI_VALUE>>",
                "status": "<<STATUS_VALUE>>"
            }
        ],
        "time": "2023-03-02:04-52-17 GMT",
        "items": <<TOTAL_ITEM_COUNT>>
    }
}

Success response format (if admin value = true)

Copy

{
    "handsets": {
        "timeStamp": 1677734236775,
        "productVersion": "master",
        "modelVersion": "2.21.0.0",
        "handset": [
            {
                "connectionProperties": {
                    "property": [
                        {
                            "name": "device-host",
                            "content": "<<VALUE>>"
                        },
                        {
                            "name": "device-host-type",
                            "content": "<<VALUE>>"
                        },
                        {
                            "name": "dns-name",
                            "content": "<<VALUE>>"
                        },
                        {
                            "name": "mac-host",
                            "content": "<<VALUE>>"
                        }
                    ]
                },
                "osBuild": "",
                "roles": {
                    "role": [
                        <<ROLES>>
                    ]
                },
                "link": {
                    "type": "<<LINK_TYPE_VALUE>>"
                },
                "available": false|true,
                "description": "<<DESCRIPTION>>",
                "language": "<<LANGUAGE>>",
                "imsi": "<<IMSI>>",
                "assetTag": "<<ASSET_TAG_VALUE>>",
                "deviceId": "<<DEVICE_ID>>",
                "resolution": "<<RESOLUTION>>",
                "operator": {
                    "country": "<<COUNTRY>>",
                    "code": <<CODE>>,
                    "name": "<<NAME>>",
                    "content": "<<CONTENT>>"
                },
                "manufacturer": "<<MANUFACTURER_VALUE>>",
                "wifiMacAddress": "<<WIFI_MAC_ADDRESS_VALUE>>",
                "mode": "<<MODEL_VALUE>>",
                "osVersion": "<<OS_VERSION>>",
                "model": "<<MODEL_VALUE>>",
                "firmware": "<<FIRMWARE_VALUE>>",
                "os": "<<OS_VALUE>>",
                "cpuArch": "<<CPU_ARCH_VALUE>>",
                "originalDeviceId": "<<ORIGINAL_DEVICE_ID>>",
                "phoneNumber": "<<PHONE_NUMBER>>",
                "lastCradleId": "<<LAST_CRADLE_ID>>",
                "reserved": false|true,
                "location": "<<LOCATION_VALUE>>",
                "distributer": "<<DISTRIBUTOR_VALUE>>",
                "nativeImei": "<<NATIVE_IMEI_VALUE>>",
                "status": "<<STATUS_VALUE>>",
                "deviceLocation": "<<DEVICE_LOCATION_VALUE>>"
            }
        ],
        "time": "2023-03-02:05-17-16 GMT",
        "items": <<TOTAL_ITEM_COUNT>>
    }
}

Error response

Copy

Error response format

[
    {
        "userMessage":"ERROR_MESSAGE",
        "developerMessage": "1-63dbebb1-4521fab52df9f41a578221c8"
    }
]

where:

userMessage is the error message to be shown.
developerMessage is a value that you can send to Perfecto Support to check errors if further investigation is required.

Sample error responses

Copy

A wrong securityToken is passed in the request (Unauthorized Request Code - 401)

[
    {
        "userMessage": "Unable to authenticate bearer token",
        "developerMessage": "Unable to authenticate bearer token"
    }
]

Copy

An invalid linkType is passed in the request (Bad Request Code - 400)

[
    {
        "userMessage": "Invalid link type 'abc'",
        "developerMessage": "6abcdb41bbe648769d2ccb7d0a5a1627"
    }
]

Copy

A device object is missing in the request (Bad Request Code - 400)

[
    {
        "userMessage": "Missing Device request object",
        "developerMessage": "5419ee50fde14676a8304c588e77b389"
    }
]