Devices
KOLO™ devices are GP PRO dispensers equipped with KOLO™ sensors to monitor product usage.
GET /devices
The GET /devices endpoint provides real-time data on the current state and operational conditions of KOLO™ devices. This API enables developers to monitor devices across various facility locations, integrating device data into applications like work order and task management systems, facility maps, and digital twins. It is ideal for identifying the current status of consumables, battery life, and fault conditions on KOLO devices, allowing for both immediate updates and customized alert logic (independent of the business logic applied at the GET /alerts endpoint) to determine action. This endpoint also serves to affirm system functionality, giving customers confidence in device operations.
Recommended Polling Interval: Updates should be made no more frequently than every 1 minute. If using GET /devices to trigger notifications, a 5-minute interval is advised.
Request
Query Parameters
(all parameters are optional)
| Parameter | Type | Description |
|---|---|---|
| building_id | string | Unique identifier for the building where the device is located |
| floor_id | string | Unique identifier for the floor where the device is located |
| room_id | string | Unique identifier for the room where the device is located |
| device_location_id | integer | Unique identifier for the device’s location within the room |
| device_macid | string | Unique 12-digit hexadecimal identifier of the physical device installed in the device location |
| device_off | boolean | Set to false to return only online devices |
| limit | integer | Count of records to be fetched in a request with offset pagination. limit would fetch the specified list of records for the device_location_id count instead of entire set of records. If not specified, defaults to 100 |
| offset | integer | Count of records to be ignored from the start. offset is used along with limit. If not specified, defaults to 0 |
Response
STATUS CODE - 200: 200 response
Attributes
| Attribute | Type | Description |
|---|---|---|
| device_location_id | string | Unique identifier for the device’s location within the room |
| device_location_name | string | Unique name for the device’s location within the room |
| device_type | string | Type of the device |
| device_state | array[object] | Contains object that are associated with a device or set of devices. Details of the states are listed in following table |
device_state Attributes
| Attribute | Type | Description |
|---|---|---|
| device_state_type | string | Expected value is “2.0” or “1.0” |
| device_macid | string | Unique 12-digit hexadecimal identifier (EUI) of the physical device installed in the device location. |
| jam_fault | array[bool] | Kolo 1.0: Array of Boolean value indicating if the device has a jam fault (e.g., [false, false]) Kolo 2.0: Few of the fault state (like Motor Stall, Tear Bar Stuck, etc) are represented as single jam_fault boolean value (e.g., [true]) |
| sensor_fault | array[bool] | Kolo 1.0: Single boolean value indicating if there is a sensor fault (e.g., [false]) Kolo 2.0: Few of the fault state (like Sensor Occluded, Sensor data out of range or communication faults etc.) are represented as single sensor_fault boolean value (e.g., [false]) |
| system_fault | array[bool] | Kolo 1.0: Single boolean value indicating if there is a system fault (e.g., [true]) Kolo 2.0: Few of the fault state (like Calibration/System/Memory Fault/Other etc.) are represented as single system_fault boolean value (e.g., [true]) |
| calibration_fault | array[bool] | Kolo 1.0: Single boolean value indicating if there is a calibration fault (e.g., [true]) Kolo 2.0: calibration_fault is redundant in Kolo 2.0 and this fault is merged into system_fault |
| communication_fault | array[bool] | Kolo 1.0: Single boolean value indicating if there is a communication fault (e.g., [true]) Kolo 2.0: communication_fault is redundant in Kolo 2.0 and this fault is merged into sensor_fault |
| incorrectly_loaded | array[bool] | Kolo 1.0: Single boolean value indicating if there is an incorrectly loaded fault (e.g., [true]) Kolo 2.0: incorrectly_loaded is redundant in Kolo 2.0 and this fault is merged into sensor_fault |
| leak | array[bool] | Kolo 1.0: Single boolean value indicating if there is a leak (e.g., [true]) Kolo 2.0: leak is redundant in Kolo 2.0 |
| maintenance_required | array[bool] | Kolo 1.0: Single boolean value indicating if there is a maintenance required fault (e.g., [true]) Kolo 2.0: maintenance_required is redundant in Kolo 2.0 |
| no_i2c_communication | array[bool] | Kolo 1.0: Single boolean value indicating if there is a no_i2c_communication fault (e.g., [true])Kolo 2.0: no_i2c_communication is redundant in Kolo 2.0 |
| safety_check | array[bool] | Kolo 1.0: Single boolean value indicating if there is a safety_check fault (e.g., [true])Kolo 2.0: safety_check is redundant in Kolo 2.0 |
| tear_bar_fault | array[bool] | Kolo 1.0: Single boolean value indicating if there is a tear_bar_fault fault (e.g., [true])Kolo 2.0: tear_bar_fault is redundant in Kolo 2.0 and this fault is merged into jam_fault |
| user_sensor_occluded | array[bool] | Kolo 1.0: Single boolean value indicating if there is a user_sensor_occluded fault (e.g., [true])Kolo 2.0: user_sensor_occluded is redundant in Kolo 2.0 |
| product_level | array[int] | List indicating product levels in different compartments within the device (e.g., [0, 0, 0, 0]). See product_low and product_out attributes for creating actions or notifications for product replenishment. |
| battery_level | array[int] | Single integer value representing the battery level of the device. See battery_low and battery_out attributes for creating actions or notifications for battery replenishment (e.g., [false, true]) |
| product_low | array[bool] | List of boolean values indicating if the product is running low in each compartment. |
| product_out | array[bool] | List of boolean values indicating if the product is out in each compartment. Recommended attribute to use as a trigger to create a notification to replenish product. |
| battery_state | string | Status of the battery (e.g., Normal, Low or Shutdown). Recommended attribute value of Low to use as a trigger to create a notification to replenish batteries. |
| last_seen | timestamp | The last recorded timestamp of an event successfully transmitted from the device (RFC 339 format) (e.g., "2025-03-06T05:35:32Z") |
| device_off | array[bool] | Single boolean value indicating if the device is offline. Is TRUE if a device has not communicated within 24 hours (e.g., [true]) |
Response Code
| Status Code | Description |
|---|---|
| 200 | Successful Execution |
| 400 | Bad Request |
| 401 | Authorization information is missing or invalid |
| 403 | x-api-key or Authorization in header is missing or invalid |
| 404 | Resource or parameter specified cannot be found |
| 500 | Internal Server Error |
Sample Response
[
{
"device_location_id": "65471534",
"device_location_name": "LoRa Gateway-1",
"device_type": "collector",
"device_state_type" : "2.0",
"device_state": [
{
"device_macid": "c0ee4029621e",
"position": "MAIN",
"faults": {
"jam_fault": [false],
"sensor_fault": [false],
"system_fault": [false],
"calibration_fault": [false],
"communication_fault": [false],
"incorrectly_loaded": [false],
"leak": [false],
"maintenance_required": [false],
"no_i2c_communication": [false],
"safety_check": [false],
"tear_bar_fault": [false],
"user_sensor_occluded": [false]
},
"status": {
"product": [100,10],
"product_low": [false, true],
"product_out": [false,false],
"battery_level": "100",
"battery_state": "NORMAL"
},
"last_seen": "2025-03-09T08:31:48Z",
"device_off": false
}
]
}
]