Manage devices

The Knox Asset Intelligence APIs provide functionalities for device management, allowing greater visibility into a device’s status and health. This tutorial focuses on how to manage your devices.

Prerequisites

Ensure that you have the necessary permissions to set or update the Knox Asset Intelligence settings and obtain an authentication token. For more information, see Get started.

Get device information

1. To retrieve essential details about the registered devices, such as model, serial number, permissions, firmware, and operating system version, make a POST request to the /devices/getDevices endpoint.

2. In the request body, you can make use of the following optional parameters:

   • pageNum — Page number to retrieve.
   • pageSize — Number of items on a page.
   • deviceIds — List of the device IMEIs or serial numbers for targeted retrieval.
   • status — List of Knox Asset Intelligence enrollment statuses.
   • batterySoh — List of battery health statuses you want information about.
   • groupName — Name of the Knox Asset Intelligence device group you want information about.

For example, the response of the following request body provides the details of those devices which have their IMEIs listed in deviceIds, whose status is Active, whose battery health is either Good or Normal and the location permission is enabled, and which are a part of device group Group A.

{
  "pageNum": 2,
  "pageSize": 50,
  "deviceIds": [
      123456789123456,123123123123123 
    ],
  "status": [
      "Active" 
    ],
  "batterySoh": [
      "Good", "Normal" 
    ],
  "permissions": [
      "Location"
    ],
  "groupName": "Group A"
}

You can adjust the parameter values in the request body according to the kind of information you want to fetch. For detailed response schema, see POST /devices/getDevices.

Retrieve information about device groups

1. To retrieve a list of all device groups in your tenant, make a GET request to the /devices/groups endpoint.

2. In the request, you can make use of the following optional parameters:

   • pageNum — Page number to retrieve.
   • pageSize — Number of items on a page.
   • groupName — Name of the Knox Asset Intelligence device group you want information about.

For example, the following sample request provides the information about the abc group. It’s response includes details such as the number of groups, group name, its description, the device count in a group, manager, and last modified time.

GET 
/devices/groups?
groupName=abc

You can modify the group name in the above request to reflect the specific group for which you want to retrieve information. For detailed response schema, see GET /devices/groups.

Assign group for a device

You can group devices for easy organization and management. You can also use the groups as filters on the Knox Asset Intelligence dashboard.

1. To assign groups for devices, make a POST request to the /devices/groups endpoint.

2. In the request body, you can use the request parameter. It’s a required parameter, and is an array of objects containing the following elements:

   • deviceId — The device IMEIs or serial numbers for which you want to assign a group.
   • groupName — Name of the Knox Asset Intelligence device group to be assigned to the device.

For example, consider the following sample request which provides the status of the request, that is whether the devices with IDs AABBCC1DDEE and AAABBB1CCCC are successfully assigned to groups A and B respectively or not.

{
  "request": [
    {
      "deviceId": "AABBCC1DDEE",
      "groupName": "group A"
    },
    {
      "deviceId": "AAABBB1CCCC",
      "groupName": "group B"
    }
  ]
}

You can adjust the request body parameters based on how you want to group the devices in your tenant. For detailed response schema, see POST /devices/getDevices.

Ensure that you check the code and message in the response for any errors and handle them appropriately for your app. For detailed specification, see Knox Asset Intelligence API.