Alerts

An alert is a condition on the device derived from a set of processed events, parameters and logic.

GET /alerts

The GET /alerts endpoint provides historical and current alert data on KOLO™ devices based on specific conditions. This API enables developers to track and manage device status changes and to integrate alert data into work order management systems, task management platforms, and reporting tools. It is particularly useful for automating workflows, generating event-driven reports, and building a history of alert data over time. This endpoint is ideal for customers who prefer not to create custom alert logic and wish to rely on KOLO’s alert processing.

Recommended polling intervals: Updates should be made no more frequently than every 1 minute. If using GET /alerts to trigger notifications, a 5-minute interval is advised. To reduce the frequency of polling, consider implementing the webhooks feature for real-time notifications.

Alert Descriptions

alert_type	device_type impacted	Description	Recommended Action
jam_fault	towel soap sanitizer	Dispenser will not be able to dispense product. This could be caused by tear bar issues, motor stalls or refills are incorrectly loaded.	Remove refill and all excess material or debris. Reinstall refill to clear jam.
sensor_fault	towel soap sanitizer	Sensor out of range, communications fault or handwave sensor issue.	Check for obstructions near handwave sensor, then wipe down hand-wave lens and wipe down sensor lens if it is a towel dispenser.
system_fault	tissue towel soap sanitizer	Device has an internal issue. Device is not functional.	Contact GP/KOLO rep for next steps and device replacement.
battery_out	tissue towel soap sanitizer	Batteries are at critically low level. For automated dispensers (towel, sanitizer and soap) this will result in device not being able to dispense. For non-automated dispensers (tissue) this will result in eventual device_off alert.	Replace the existing batteries with fully charged batteries.
consumable_out	tissue towel soap sanitizer	Refill/consumable is near out or completely out.	Replace the depleted refill with a full refill.
incorrectly_loaded sensor_fault toto_leak toto_safety_check	tissue towel soap sanitizer toto	Other types of external alerts	Other types of external alerts

Request

Query Parameters

(all parameters are optional)

Parameter	Type	Description
alert_id	string	Unique identifier for this specific alert
building_id	string	Unique identifier for the building where the alert originated
floor_id	string	Unique identifier for the floor where the alert originated
room_id	string	Unique identifier for the room where the alert originated
device_location_id	integer	Unique identifier for the device’s location. Filters alerts for a specific device location
alert_status	string	Current status of the alert (e.g., `OPEN`, `CLOSED`). Filter by alert status. Possible values are OPEN or CLOSED. Omit to retrieve alerts regardless of status
alert_type	string	Type of alert (e.g., `DEVICE_OFF`). Filter alerts by specific alert type
resolution_type	string	Describes how the alert was resolved: `resolved`: By a device event `resolved_by_offline`: Auto-resolved due to device going offline `resolved_by_user`: Manually resolved by user.
start_date	string	Start date in UTC ISO 8601 format. Defaults to 7 days before today at 00:00:00 UTC if not specified. If `alert_status` is `OPEN` or not specified, alerts will be filtered by alert creation date. If `alert_status` is `CLOSED`, alerts will be filtered by alert resolution date.
end_date	string	End date in UTC ISO 8601 format. Defaults to tomorrow’s date at 00:00:00 UTC if not specified. If `alert_status` is `OPEN` or not specified, alerts will be filtered by alert creation date. If `alert_status` is `CLOSED`, alerts will be filtered by alert resolution date.
page_size	integer	Number of alerts per page. Defaults to 100, with a maximum limit of 500.
next	string	Base64 encoded cursor to retrieve the next page of alerts. If specified, all other query parameters (except `page_size`) will be ignored.
prev	string	Base64 encoded cursor to retrieve the previous page of alerts. If specified, all other query parameters (except `page_size`) will be ignored.

Response

STATUS CODE - 200: 200 response

Attributes

Attribute	Type	Description
alert_id	string	Unique identifier for this specific alert
device_location_id	string	Unique identifier for the device’s location within the room
device_macid	array	Unique 12-digit hexadecimal identifier of the physical device installed in the device location
alert_status	string	Current status of the alert (e.g., `OPEN`, `CLOSED`)
alert_type	string	Type of alert (e.g., `DEVICE_OFF`)
created_date	string	Timestamp of when the alert was created (in milliseconds)
resolved_date	string	Timestamp of when the alert was resolved (in milliseconds), or `null` if still open
resolution_type	string	Describes how the alert was resolved: `resolved`: By a device event `resolved_by_offline`: Auto-resolved due to device going offline `resolved_by_user`: Manually resolved by user
overdue	boolean	Boolean flag indicating if the alert is overdue for resolution
refill_count	integer	`refill_count` limited to Consumable out and Battery out. For other alerts, it would be 0 Consumable Out : Count would be initialised on the product low or product out. Alert raised on alert preference either low or out - Quad Tissue device type having 4 rolls consumable out or low: Count would be 4 - Quad Tissue device type having 2 rolls consumable out or low: Count would be 2 - Quad Tissue device type having 1 rolls consumable out or low: Count would be 1 Battery Out : Count would be initialised on the depletion state of battery set - Quad Tissue device type having both battery set depleted: Count would be 2 - Vertical Tissue, Towel or any other device type having battery set depleted : Count would be 1

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

  {
    "next": "base64 encoded cursor ",
    "prev": "base64 encoded cursor",
    "alerts": [{
      "alert_id": "9c95a25b-1587-4376-b214-c5d4db9212e7",
      "device_location_id": "29325843",
      "device_macid": ["a528b8c4defg"],
      "alert_status": "CLOSED",
      "refill_count": 1,
      "alert_type": "BATTERY_OUT",
      "created_date": "2025-02-26T01:08:14.424Z",
      "resolved_date": "2025-02-26T03:08:25.23Z",
      "resolution_type": "RESOLVED_BY_OFFLINE",
      "overdue": false
    },
    { }
   ]
  }

Alerts

GET /alerts#

Alert Descriptions#

Request#

Query Parameters#

Response#

Attributes#

Response Code#

Sample Response#