Sensaphone.net API/zone
Contents
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 |
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/zoneJSON 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 |
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 | is_last_ack_supported | Optional | Boolean | Whether or not last acknowledge is supported |
alarm_zone | is_last_alarm_supported | Optional | Boolean | Whether or not last alarm is supported |
alarm_zone | last_ack | Optional | String | The date of the last acknowledge |
alarm_zone | last_alarm | Optional | String | The date of the last alarm |
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 | clear_min | Optional | Boolean | Clear the minimum value. |
analog_zone | clear_max | 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 } ] } ] } } }