Devices Resource

Provides device management functions.

GET /{tenantGuid}/api/v1/devices

Available Since:
12.7.0

Search for devices.

Samples

Sample 1 request

Get the device with an IMEI of "990000862471854". 

 GET /SRP00000/api/v1/devices?query=imei=990000862471854

Sample 1 response body

 
 {
   "devices": [ {
     "links" : [ {
       "rel" : "userDevice",
       "href" : "https://server01:18084/SRP00000/api/v1/users/6dd3a8e2-3f24-48c6-961a-949794f4b554/userDevices/2d2d3a7f-076d-46f9-8c25-56cb8eba2800"
     }, {
       "rel" : "sharedDeviceGroup",
       "href" : "https://server01:18084/SRP00000/api/v1/sharedDeviceGroups/361287bf-d2b9-4a3a-80db-0da4c80de5f2"
     } ],
     "guid": "4659aa7f-0a7d-9f69-258c-2800ebaa2800",
     "activationDate": "2017-01-16T14:47:03.662Z",
     "activeSyncId": "K6CKULJTID3SDEAIV0ELHBBTTO",
     "batteryLevel": 95.0,
     "compromised": false,
     "externalStorageFree": 12021.0,
     "externalStorageSize": 16386.0,
     "hardwareModel": "Desire",
     "hardwareName": "bravo",
     "hardwareVendorCompanyName": "HTC Corporation",
     "homeCarrier": "Rogers",
     "currentCarrier": "Rogers",
     "networkRoaming": false,
     "internalStorageFree": 2112.0,
     "internalStorageSize": 32768.0,
     "imei": "990000862471854",
     "os": "Android 5.0",
     "osFamilyName": "android",
     "osVersion": "5.0",
     "ownership": "PERSONAL",
     "phoneNumber": "4045551234",
     "serialNumber": "c08088415436112",
     "udid": "d88496fdf7115ac9f3ab69966cbaf91d960b95036fa68f66489c8ad78f136b5c",
     "wifiMacAddress": "62:9a:7e:bc:fe:01",
     "clientId": "com.rim.mobilefusion.client",
     "clientVersion": "12.34.0.154893", 
     "ramTotal": 4096,
     "ramFree": 3556.0
   } ]
 }

Sample 2 request

Get the first 50 devices sorted by OS in descending order. If 50 devices are returned, there may be more matches that weren't returned. You can get the next "page" of devices by sending the same request but also specifying offset=50. If 50 devices are returned again, you can get the third "page" of devices by modifying the request again and specifying offset=100, and so on. 

 GET /SRP00000/api/v1/devices?max=50&sortBy=os%20DESC

Sample 2 response body

 
 {
   "devices": [ {
     "links" : [ {
       "rel" : "userDevice",
       "href" : "https://server01:18084/SRP00000/api/v1/users/6dd3a8e2-3f24-48c6-961a-949794f4b554/userDevices/59dc743d-f325-4a6c-97ac-44dcb9ef8a0e"
     } ],
     "guid": "8002ebaa-c258-96f9-d7a0a-0082aa7f4659",
     "activationDate": "2017-01-16T14:47:03.662Z",
     "activeSyncId": "Q633AGG6QP3FJF6QBNAA81UHB0",
     "batteryLevel": 64.0,
     "compromised": false,
     "externalStorageFree": 12021.0,
     "externalStorageSize": 16386.0,
     "hardwareModel": "Desire",
     "hardwareName": "bravo",
     "hardwareVendorCompanyName": "HTC Corporation",
     "homeCarrier": "Rogers",
     "currentCarrier": "Vodafone",
     "networkRoaming": true,
     "internalStorageFree": 2112.0,
     "internalStorageSize": 32768.0,
     "imei": "351756051523999",
     "meid": "01234567890123456",
     "ownership": "CORPORATE",
     "os": "Android 6.0",
     "osFamilyName": "android",
     "osVersion": "6.0",
     "phoneNumber": "2125557890",
     "securityPatchLevel": "6.0.1.1345",
     "serialNumber": "c03618841215084",
     "udid": "82f2aaa813c5a4bc2748b078ca844bdbd6a8fb8eaaa173a389467646cf04d00c",
     "wifiMacAddress": "b4:52:7e:62:a5:9a",
     "clientId": "com.rim.mobilefusion.client",
     "clientVersion": "12.34.0.154893"
   }, {
     "links" : [ {
       "rel" : "userDevice",
       "href" : "https://server01:18084/SRP00000/api/v1/users/6dd3a8e2-3f24-48c6-961a-949794f4b554/userDevices/2d2d3a7f-076d-46f9-8c25-56cb8eba2800"
     } ],
     "guid": "4659aa7f-0a7d-9f69-258c-2800ebaa2800",
     "activationDate": "2017-01-16T14:47:03.662Z",
     "activeSyncId": "K6CKULJTID3SDEAIV0ELHBBTTO",
     "batteryLevel": 95.0,
     "compromised": false,
     "externalStorageFree": 12021.0,
     "externalStorageSize": 16386.0,
     "hardwareModel": "Desire",
     "hardwareName": "bravo",
     "hardwareVendorCompanyName": "HTC Corporation",
     "homeCarrier": "Rogers",
     "internalStorageFree": 2112.0,
     "internalStorageSize": 32768.0,
     "imei": "990000862471854",
     "os": "Android 5.0",
     "osFamilyName": "android",
     "osVersion": "5.0",
     "ownership": "PERSONAL",
     "phoneNumber": "4045551234",
     "serialNumber": "c08088415436112",
     "udid": "d88496fdf7115ac9f3ab69966cbaf91d960b95036fa68f66489c8ad78f136b5c",
     "wifiMacAddress": "62:9a:7e:bc:fe:01",
     "clientId": "com.rim.mobilefusion.client",
     "clientVersion": "12.34.0.154893",
     "ramTotal": 6144,
     "ramFree": 1028.4
   } ]
 }

Sample 3 request

Get the device with a BlackBerry Dynamics container GUID of "71D6F61F-6996-4360-8D74-36A9D1637A23". 

 GET /SRP00000/api/v1/devices?query=dynamicsContainerId=71D6F61F-6996-4360-8D74-36A9D1637A23

Sample 3 response body

 
 {
   "devices": [ {
     "links" : [ {
       "rel" : "userDevice",
       "href" : "https://server01:18084/SRP00000/api/v1/users/6dd3a8e2-3f24-48c6-961a-949794f4b554/userDevices/2d2d3a7f-076d-46f9-8c25-56cb8eba2800"
     },{
       "rel": "userDeviceApplication",
       "href": "https://server01:18084/SRP00000/api/v1/users/6dd3a8e2-3f24-48c6-961a-949794f4b554/userDevices/2d2d3a7f-076d-46f9-8c25-56cb8eba2800/applications/b6df080a-98b8-41a7-8498-49644c793d70"
     }],
     "guid": "4659aa7f-0a7d-9f69-258c-2800ebaa2800",
     "activationDate": "2017-01-16T14:47:03.662Z",
     "activeSyncId": "K6CKULJTID3SDEAIV0ELHBBTTO",
     "batteryLevel": 95.0,
     "compromised": false,
     "externalStorageFree": 12021.0,
     "externalStorageSize": 16386.0,
     "hardwareModel": "Desire",
     "hardwareName": "bravo",
     "hardwareVendorCompanyName": "HTC Corporation",
     "homeCarrier": "Rogers",
     "networkRoaming": false,
     "internalStorageFree": 2112.0,
     "internalStorageSize": 32768.0,
     "imei": "990000862471854",
     "os": "Android 5.0",
     "osFamilyName": "android",
     "osVersion": "5.0",
     "ownership": "PERSONAL",
     "phoneNumber": "4045551234",
     "serialNumber": "c08088415436112",
     "udid": "d88496fdf7115ac9f3ab69966cbaf91d960b95036fa68f66489c8ad78f136b5c",
     "wifiMacAddress": "62:9a:7e:bc:fe:01",
     "clientId": "com.rim.mobilefusion.client",
     "clientVersion": "12.34.0.154893",
     "ramTotal": 6144,
     "ramFree": 1028.4
   } ]
 }

Request Parameters
Name Location Description Type
includeTotal query If you want the total number of devices matching the search included in the response (which may be different from the number of devices actually returned) set this to true; otherwise set to false. By default the total will not be included in the response. boolean
max query The maximum number of device results to get, between 1 and 1000 inclusive. If not specified, a value of 100 will be used. int
offset query The number of matching devices to exclude from the beginning of the list of devices in the response; greater than or equal to 0. If not specified, a value of 0 will be used to indicate that no matches should be excluded. Used in order to get "pages" of results. For example, to get the first 50 matching devices, specify max=50 (and optionally offset=0); and to get the next 50 matching devices specify max=50 and offset=50, and so on. int
query query Query parameter for filtering the results. The format is <field name>=<query value>, for example imei=990000862471854. Multiple field-value pairs can be provided in the query with each pair separated with a comma, in which case only devices matching all of the criteria provided will be included in the response. Querying for empty/null values is not supported.

By default, a case-insensitive exact match will be performed for each field in the query. For fields that support prefix (i.e. starts with) matching, append an asterisk ("*") to the end of the value. To match an asterisk at the end of a string instead of prefix matching, the asterisk must be escaped with a backslash.

Special characters (comma, backslash) in query values must be escaped with a backslash.

The following table describes the fields that can be used in the query.

Field Type Description Supports prefix matching
activationDate string Date value in ISO-8601 format yyyy-MM-ddTHH:mm:ss.SSSZ. Use operators > or >= for the minimum date, and/or < or <= for the maximum date. For example: activationDate>=1970-01-01T00:00:00.000Z,activationDate<=1970-12-31T23:59:59.000Z. No
dynamicsContainerId string Identifier of a Dynamics container that is activated on a device. When searching by a BlackBerry Dynamics container Id, response will additionally contain user-device application route link that corresponds to the Dynamics application to which the container belongs and the user who owns the device. No
guid string GUID of the device. No
imei string IMEI of the device. No
meid string MEID of the device. No
ownership string 'CORPORATE' or 'PERSONAL' No
udid string UDID of the device. No
wifiMacAddress string WIFI MAC address of the device. No
sharedDeviceOnly boolean Filter to return only devices that are part of shared device groups. If filter is not specified then all the devices will be returned No
 
sortBy query The field to sort the device results by. The format is <field name> ASC|DESC, where ASC means to sort the results in ascending order and DESC means descending order. For example, to sort the results by OS in descending order, specify os DESC. If not specified, a value of hardwareModel ASC will be used. The following fields are allowed: hardwareModel, osFamilyName, os.  
Response Codes
Code Condition Data type
200 OK (even if no devices are found).
400 Invalid search query.
Response Body
Media type Data type Description
application/vnd.blackberry.devices-v1+json Devices (JSON)