Clear a Check

Base URL

https://{SERVER}/api/?apikey={yourAPIkey}&service=clear_check

Description

Clear a check status. After a check has failed, mark it as 'cleared', thereby acknowledging the cause of the failure.The check will be shown using an amber tick. A note describes the reason for the failure and the action taken by the engineer.

This API call is only supported where Check Clearing is enabled on the account for this check frequency type, i.e. 24x7 and/or Daily Safety Check.
Only Checks that are currently in the failing state (red exclamation box on the All Devices view) can be cleared.
Where the option to Prompt for notes when clearing failed checks is enabled in the N-sight UI at Settings > General Settings> Notes, both the public note (customer facing) and the private note (for engineers) must be non-empty.
- For example: https://{SERVER}/api/?apikey={yourAPIkey}&service=clear_check&checkid=X&public_note=Public%20Note&private_note=Private%20Note
All check clearing actions add an entry in the User Audit Report.

Parameters

Required parameters

Add required parameters immediately after the base URL.

https://{SERVER}/api/?apikey={yourAPIkey}&service=clear_check&required_parameters={parameter-value}

Parameter	Type	Description	Options
describe	Boolean	Optional. Returns a description of the service.	0
checkid	Number	The ID of the Check you want to clear.	0
private_note	String	Technical (private) note	0
public_note	String	Client-facing note	0
clear_type	String	Optional. Action taken on clearing check untilpasses, untilnextrun, or untildatetime*. Reverts to default if not provided.	untilpasses untilnextrun untildatetime
clear_until	Datetime	Optional. *If untildatetime is selected as the clear_type then this date/time value is required to determine how long a check will be cleared until. Format is ISO-8601, e.g. 2024-10-21 11:22:33	0

Optional parameters

Add optional parameters immediately after the base URL.

https://{SERVER}/api/?apikey={yourAPIkey}&service=clear_check&optional_parameters={parameter-value}

Parameter	Description	Type	Required	Options	Default
describe	Returns a description of the service.	boolean	no	true	0

Determine parameter values

Use the following associated service calls to determine parameter values.

Parameter	Call	URL Format
checkid	list_checks	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_checks&deviceid=DEVICEID
deviceid	list_devices_at_client	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_devices_at_client&clientid=CLIENTID&devicetype=server
	list_servers	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_servers&siteid=SITEID
	list_workstations	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_workstations&siteid=SITEID
siteid	list_sites	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_sites&clientid=CLIENTID
clientid	list_clients	https://`{SERVER}`/api/?apikey=`{yourAPIkey}`&service=list_clients

Examples

Clear a check

https://{SERVER}/api/?apikey={yourAPIkey}&service=clear_check&checkid=CHECKID&clear_type=untildatetime&clear_until=CLEAR_UNTIL

Example response

<?xml version="1.0"?>
<result created="2024-03-25T16:20:24+00:00" host="SERVER" status="OK">
  <message><![CDATA[check cleared]]></message>
</result>

Returned fields

Field	Type	Can Be Empty	Description
message	string	no	Message relating to clear check state