Sensaphone.net API

Specifications

Different zones types may have different configurable properties than others. For example, a 2.8k Thermistor F type Zone will have calibration, alarm low, and alarm high but a Normally Open type zone will not. If a request is made for a property not belonging to a zone type an error will be issued. Below is a chart showing the relations. A property is only available if the type metadata (The type_list property) has the checked options enabled. Whether or not the above properties correspond with a particular zone type is defined in the meta data for the zone types (included in v2 but not v1 of the API). In addition, a property may be disabled at the global scale if it is 'null', regardless of this table. For example, the zone type's meta indicates that it is "External" but the "wireless_zone" field is 'null' on a "read".

Type Dependent Properties

Property

Digital

Analog

Internal

External

Generic

Input

Output

IP Alarm

Alarmable

Table Ranged

Loggable

Alarm Low

Alarm High

wireless_zone

✓

pulse_zone

✓

runtime_zone

✓

output_zone

✓

alarm_zone

✓

table_zone

✓

loggable_zone

✓

alarm_low

✓

alarm_high

✓

modbus_zone

✓

Zone States

Zone State	Value
None	0
Alarm	1
OK	2
Pending	3
Open	4
Closed	5
Cycle	6
Low	7
High	8
Off	9
On	10
Return To Normal	11
Route Down	12
Trouble	13
Not Responding	14
Dependency Failure	15
Battery	16
Acknowledged	17
Unacknowledged	18

Output Mode Type

Child Property	Type	Description
name	String	Name
action	String	Action
zone_list	Array of Objects	List of zones
type_list	Array of Objects	List of Zone type
trigger	String	Trigger
compare_on	String	Compare On
compare_off	String	Compare Off
limit_on	Float	Limit On
limit_off	Float	Limit Off
zone_on	String	Zone On
zone_off	String	Zone Off

GET

An error will be issued if attempting to receive a Zone property that does not correspond to the Zone type.

URI Mode Request URI's:

Retrieve all information for every one of a device's zones.

  GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone

Retrieve all information for a single zone.

  GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone/{ZONE_ID}

Retrieve the a specific zone's type.

  GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone/{ZONE_ID}/type

JSON Mode Request URI:

  POST https://rest.sensaphone.net/api/v1/device/zone

JSON Mode Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	Integer	Session ID
	request_type	String	"read"
	device	Array of Objects	The parent device of the "zone" resource. See device.
device	zone	Array of Objects	The zone object

JSON Mode Response Properties

Parent Property	Child Property	Status	Type	Description
	device	Required	Array of Objects	The parent device object.
device	zone	Required	Array of Objects	The zone object.
zone	zone_id	Required	Integer	ID of the zone.
zone	index_id	Optional	Integer	Zone ordering.
zone	name	Optional	String	Name of the zone.
zone	canonical_name	Optional	String	Canonical name of the zone.
zone	type	Optional	String	The zone type. (Use a V2 read command to retrieve the valid values)
type	type_list	Optional	Array of Objects	The zone type metadata.
type_list	name	Optional	Boolean	Zone Type Metadata: Name corresponds to the ranged values for the zone type.
type_list	is_digital	Optional	Boolean	Zone Type Metadata: Digital
type_list	is_analog	Optional	Boolean	Zone Type Metadata: Analog
type_list	is_internal	Optional	Boolean	Zone Type Metadata: Internal
type_list	is_external	Optional	Boolean	Zone Type Metadata: External
type_list	is_generic	Optional	Boolean	Zone Type Metadata: Generic
type_list	is_input	Optional	Boolean	Zone Type Metadata: Input
type_list	is_output	Optional	Boolean	Zone Type Metadata: Output
type_list	is_ipalarm	Optional	Boolean	Zone Type Metadata: IP Alarm
type_list	is_alarmable	Optional	Boolean	Zone Type Metadata: Alarmable
type_list	is_tablerange	Optional	Boolean	Zone Type Metadata: Table Ranged
type_list	is_loggable	Optional	Boolean	Zone Type Metadata: Loggable
type_list	is_alarm_low	Optional	Boolean	Zone Type Metadata: Alarm Low
type_list	is_alarm_high	Optional	Boolean	Zone Type Metadata: Alarm High
type_list	units_list	Optional	Array of Ranges	Zone Type Metadata: Possible Units
zone	enable	Optional	Boolean	Whether or not the zone is enabled.
zone	value	Optional	String	The data value for the zone.
zone	units	Optional	String	The custom units for the zone.
zone	schedule	Optional	Object	(See Sensaphone.net API/schedule)
zone	alarm_zone	Optional	Object	Sub-object containing data for alarmable zones. 'null' if unsupported.
alarm_zone	alarm_rtn	Optional	Boolean or null	Whether or not a return-to-normal alarm is enabled. 'null' if the feature is not supported.
alarm_zone	alarm_hold	Optional	Integer	The alarm hold (or clear delay) time.
alarm_zone	alarm_enable	Optional	Boolean	Whether or not alarming is enabled for this zone.
alarm_zone	rec_time	Optional	Integer	The alarm recognition time.
alarm_zone	reset_time	Optional	Integer	The alarm reset time.
alarm_zone	alarm_low	Optional	Floating Point	The alarm low limit.
alarm_zone	alarm_high	Optional	Floating Point	The alarm high limit.
alarm_zone	alarm_condition	Optional	Array of ZoneState	The highest priority ZoneState that has been reached
alarm_zone	alarm_status	Optional	Array of ZoneState	The processed status of the zone ( returns 2 ZoneStates)
alarm_zone	current_status	Optional	Array of ZoneState	The real-time status of the zone input (returns 1 ZoneState)
alarm_zone	unack_alarms	Optional	Array of ZoneState	Alarm states that are currently unacknowledged
alarm_zone	alarmschedule	Optional	Object	(See Sensaphone.net API/alarmschedule)
zone	analog_zone	Optional	Object	Sub-object containing data for analog zones. 'null' if unsupported.
analog_zone	minimum	Optional	Floating Point	The minimum "value" seen.
analog_zone	maximum	Optional	Floating Point	The maximum "value" seen.
analog_zone	calibration	Optional	Floating Point	The calibration factor applied to the "value".
zone	table_zone	Optional	Object	Sub-object containing data for table-based zones. 'null' if unsupported.
table_zone	table_low	Optional	Floating Point	The low table range for the zone. Used for 4-20mA sensors.
table_zone	table_high	Optional	Floating Point	The high table range for the zone. Used for 4-20mA sensors.
zone	log_zone	Optional	Object	Sub-object containing data for loggable zones. 'null' if unsupported.
log_zone	report_mode	Optional	String	The reporting option.
log_zone	alarm_interval	Optional	Integer	The datalogging interval for when in alarm.
log_zone	normal_interval	Optional	Integer	The datalogging interval for when not in alarm.
log_zone	enable	Optional	Boolean	Whether or not datalogging is enabled.
zone	pulse_zone	Optional	Object	Sub-object containing data for pulse count capable zones. 'null' if unsupported.
pulse_zone	enable	Optional	Boolean	Whether or not pulse counting is enabled for this zone.
pulse_zone	multiply	Optional	Integer	The multiplication factor to apply to each pulse.
pulse_zone	count	Optional	Integer	The number of pulses seen (after multiply has been applied)
zone	runtime_zone	Optional	Object	Sub-object containing data for runtime capable zones. 'null' if unsupported.
runtime_zone	enable	Optional	Boolean	Whether or not runtime is enabled for this zone.
runtime_zone	runtime	Optional	String	The run time elapsed.
zone	modbus_zone	Optional	Object	Sub-object containing data for modbus zones. 'null' if unsupported.
modbus_zone	media_port	Optional	String	The modbus media port
modbus_zone	slave_id	Optional	Integer	The modbus slave ID
modbus_zone	command	Optional	String	The modbus command
modbus_zone	address	Optional	Integer	The modbus address
modbus_zone	byte_order	Optional	String	The modbus byte order
modbus_zone	register_order	Optional	String	The modbus register order
modbus_zone	register_size	Optional	String	The modbus register size
modbus_zone	format	Optional	String	The modbus format
modbus_zone	sign	Optional	String	The modbus sign
modbus_zone	scaling_offset	Optional	Integer	The modbus scaling offset
modbus_zone	scaling_factor	Optional	Integer	The modbus scaling factor
modbus_zone	scaling_mode	Optional	String	The modbus scaling mode
zone	output_zone	Optional	Object	Sub-object containing data for output zones. 'null' if unsupported.
output_zone	mode	Optional	Output Mode Type	The output mode
output_zone	mode_list	Optional	Array of Output Mode Type	The list of output modes
output_zone	set_point_on	Optional	Floating Point	The output set point for the "on" state.
output_zone	set_point_off	Optional	Floating Point	The output set point for the "off" state.
zone	wireless_zone	Optional	Object	Sub-object containing data for wireless zones. 'null' if unsupported.
wireless_zone	sampling_rate	Optional	Integer	The sampling rate for the sensor
wireless_zone	serial_number	Optional	Integer	The serial number for the wireless sensor.
wireless_zone	battery_level	Optional	String	The wireless sensor's battery level.
wireless_zone	power_level	Optional	String	The wireless sensor's power level.

Example JSON

Receive the status for a specific Zone.

Request JSON

  {
   "acctid": 987654,
   "uuid": "0123-4567-8901",
   "request_type": "read",
   "device":[
    {
      "device_id": 1234,
      "zone":[
       {
         "zone_id":28487,
         "status": "null"
       }
      ]
    }
   ]
 }

Response JSON

{
 "result":
 {
   "success": true,
   "code": 0,
   "message": "OK"
 },
 "response":
 {
   "device":[
    {
      "device_id": 1234,
      "zone":[
       {
         "zone_id": 28487,
         "status": "OK"
       }
      ]
    }
   ]
 }
}

PUT

URI Mode Request URI's:

Edit a Zone name

  PUT  https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone/{ZONE_ID}/name/{ZONE_NAME}

Edit a Zone's recognition time value

  PUT  https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone/{ZONE_ID}/alarm_zone/rec_time/{REC_TIME}

JSON Mode Request URI:

  POST https://rest.sensaphone.net/api/v1/device/zone

JSON Mode Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	Integer	Session ID
	request_type	String	"read"
	device	Array of Objects	The parent device of the "zone" resource. See device.
device	zone	Array of Objects	The zone object.
zone	zone_id	Integer	ID of the zone.
zone	CHILD PROPERTY		Zone's child properties to be edited*

* One or more zone child properties listed below are required in addition to "zone_id".

JSON Mode Response Properties

Parent Property	Child Property	Status	Type	Description
	device	Required	Array of Objects	The parent device object.
device	zone	Required	Array of Objects	The zone object.
zone	zone_id	Required	Integer	ID of the zone.
zone	index_id	Optional	Integer	Zone ordering.
zone	name	Optional	String	Name of the zone.
zone	type	Optional	String	The zone type. (Use a V2 read command to retrieve the valid values)
zone	enable	Optional	Boolean	Whether or not the zone is enabled.
zone	value	Optional	String	The data value for the zone.
zone	units	Optional	String	The custom units for the zone.
zone	schedule	Optional	Object	(See Sensaphone.net API/schedule)
zone	alarm_zone	Optional	Object	Sub-object containing data for alarmable zones. 'null' if unsupported.
alarm_zone	alarm_rtn	Optional	Boolean or null	Whether or not a return-to-normal alarm is enabled. 'null' if the feature is not supported.
alarm_zone	alarm_hold	Optional	Integer	The alarm hold (or clear delay) time.
alarm_zone	alarm_enable	Optional	Boolean	Whether or not alarming is enabled for this zone.
alarm_zone	rec_time	Optional	Integer	The alarm recognition time.
alarm_zone	reset_time	Optional	Integer	The alarm reset time.
alarm_zone	alarm_low	Optional	Floating Point	The alarm low limit.
alarm_zone	alarm_high	Optional	Floating Point	The alarm high limit.
alarm_zone	alarmschedule	Optional	Object	(See Sensaphone.net API/alarmschedule)
zone	analog_zone	Optional	Object	Sub-object containing data for analog zones. 'null' if unsupported.
analog_zone	minimum	Optional	Boolean	Clear the minimum value.
analog_zone	maximum	Optional	Boolean	Clear the maximum value.
analog_zone	calibration	Optional	Floating Point	The calibration factor applied to the "value".
zone	table_zone	Optional	Object	Sub-object containing data for table-based zones. 'null' if unsupported.
table_zone	table_low	Optional	Floating Point	The low table range for the zone. Used for 4-20mA sensors.
table_zone	table_high	Optional	Floating Point	The high table range for the zone. Used for 4-20mA sensors.
zone	log_zone	Optional	Object	Sub-object containing data for loggable zones. 'null' if unsupported.
log_zone	report_mode	Optional	String	The reporting option.
log_zone	alarm_interval	Optional	Integer	The datalogging interval for when in alarm.
log_zone	normal_interval	Optional	Integer	The datalogging interval for when not in alarm.
log_zone	enable	Optional	Boolean	Whether or not datalogging is enabled.
zone	pulse_zone	Optional	Object	Sub-object containing data for pulse count capable zones. 'null' if unsupported.
pulse_zone	enable	Optional	Boolean	Whether or not pulse counting is enabled for this zone.
pulse_zone	multiply	Optional	Integer	The multiplication factor to apply to each pulse.
pulse_zone	count	Optional	Integer	The number of pulses seen (after multiply has been applied)
zone	runtime_zone	Optional	Object	Sub-object containing data for runtime capable zones. 'null' if unsupported.
runtime_zone	enable	Optional	Boolean	Whether or not runtime is enabled for this zone.
runtime_zone	runtime	Optional	String	The run time elapsed.
zone	modbus_zone	Optional	Object	Sub-object containing data for modbus zones. 'null' if unsupported.
modbus_zone	media_port	Optional	String	The modbus media port
modbus_zone	slave_id	Optional	Integer	The modbus slave ID
modbus_zone	command	Optional	String	The modbus command
modbus_zone	address	Optional	Integer	The modbus address
modbus_zone	byte_order	Optional	String	The modbus byte order
modbus_zone	register_order	Optional	String	The modbus register order
modbus_zone	register_size	Optional	String	The modbus register size
modbus_zone	format	Optional	String	The modbus format
modbus_zone	sign	Optional	String	The modbus sign
modbus_zone	scaling_offset	Optional	Integer	The modbus scaling offset
modbus_zone	scaling_factor	Optional	Integer	The modbus scaling factor
modbus_zone	scaling_mode	Optional	String	The modbus scaling mode
zone	output_zone	Optional	Object	Sub-object containing data for output zones. 'null' if unsupported.
output_zone	mode	Optional	String	The output mode
output_zone	mode_list	Optional	String	The list of output modes
output_zone	set_point_on	Optional	Floating Point	The output set point for the "on" state.
output_zone	set_point_off	Optional	Floating Point	The output set point for the "off" state.
output_zone	value	Optional	Floating Point	Write Only set the value of the output zone
zone	wireless_zone	Optional	Object	Sub-object containing data for wireless zones. 'null' if unsupported.
wireless_zone	sampling_rate	Optional	Integer	The sampling rate for the sensor
wireless_zone	serial_number	Optional	Integer	The serial number for the wireless sensor.

POST

URI Mode Request URI's:

Acknowledge All Zone Alarms

  POST  https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone/{ZONE_ID}/alarm_zone/acknowledge_all_alarms/{true}

JSON Mode Request URI:

  POST https://rest.sensaphone.net/api/v1/device/zone

JSON Mode Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	Integer	Session ID
	request_type	String	"read"
	device	Array of Objects	The parent device of the "zone" resource. See device.
device	zone	Array of Objects	The zone object.
zone	zone_id	Integer	ID of the zone.
zone	alarm_zone	Object	Sub-object containing data for alarmable zones
alarm_zone	acknowledge_alarms	Array of Zone State	A write-only property to acknowledge specific alarms
alarm_zone	acknowledge_all_alarms	Boolean	A write-only property to acknowledge all alarms for a zone

* "acknowledge_all_alarms" supersedes "acknowledge_alarms", if it is present in the request json other properties will be ignored

JSON Mode Result Properties

Parent Property	Child Property	Status	Type	Description
	device	Required	Array of Objects	The parent device object.
device	zone	Required	Array of Objects	The zone object.
zone	zone_id	Required	Integer	ID of the zone.
zone	alarm_zone	Required	Object	Sub-object containing data for alarmable zones. 'null' if unsupported.
alarm_zone	acknowledge_alarms	Optional	Array of Zone State	A write-only property to acknowledge specific alarms
alarm_zone	acknowledge_all_alarms	Optional	Boolean	A write-only property to acknowledge all alarms for a zone

Example JSON

Acknowledge an alarm for a Zone

Request JSON

{
 "request_type": "create",
 "resource": "device",
 "acctid": 987654,
 "session": "0123-4567-8901",
 "device": [
   {
     "device_id": 1234,
     "zone": [
       {
         "zone_id": 7,
         "alarm_zone": {
           "acknowledge_alarms": [
             11,
             4
           ]
         }
       }
     ]
   }
 ]
}

Response JSON

{
 "result": {
   "success": true,
   "code": 0,
   "message": "OK",
   "properties": {
     "device": [
       {
         "device_id": 1234,
         "zone": [
           {
             "alarm_zone": [
               {
                 "acknowledge_alarms": 11,
                 "code": 0,
                 "message": "OK",
                 "success": true
               },
               {
                 "acknowledge_alarms": 4,
                 "code": 0,
                 "message": "OK",
                 "success": true
               }
             ],
             "zone_id": 7
           }
         ]
       }
     ]
   }
 }
}

Sensaphone.net API/zone

Contents

Sensaphone.net API

Specifications

Zone States

GET

Example JSON

PUT

POST

Example JSON

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools