Sensaphone.net API/device

Sensaphone.net API

Specifications

The device resource allows access to the devices that are bound to the account.

The device resource has the following properties:

Parent Property	Property	Type	Description	Create	Delete	Read	Update
<parent>	device	Object	The device object.	✓	✓	✓	n/a
device	device_id	Integer	ID of the device.			✓
device	id	String	Unique identifier located on the Device (Serial number, etc.)			✓
device	name	String	Name of Device			✓	✓
device	description	String	Short description of Device			✓	✓
device	timezone	String	The timezone the Device is in			✓	✓
device	location	Object	Contains location information for the device.			✓	✓
location	address	Object	Address information for Device (See Sensaphone.net API/address)			✓	✓
location	coordinates	Object	GPS Coordinates information for Device (See Sensaphone.net API/coordinates)			✓	✓
device	default_schedule	Object	Alarm Schedule data (See Sensaphone.net API/alarmschedule)			✓	✓
device	device_schedule	Object	Alarm Schedule data (See Sensaphone.net API/alarmschedule)			✓	✓
device	zone	Array of Objects	Device Zone data (See Sensaphone.net API/zone)			✓	✓
device	offline_timeout	Integer	The number of minutes a device must be offline before it goes into alarm.			✓	✓
device	product	String	The name of the product type			✓
device	modbus_ports	Array of Objects	TBD
device	zone_meta	Array of Objects	TBD			✓
zone_meta	zone	Zone Meta Type	TBD			✓
zone_meta	children	Array of Zone Meta Type	TBD			✓
device	is_offline_unack	Boolean	Whether or not an unacknowledged offline alarm exists.			✓
device	is_online	Boolean	Whether or not the device is currently online.			✓
device	standby_time	String	The number of minutes a device will be in standby mode.			✓	✓
device	standby_mode	String	A device's standby mode.			✓	✓
device	standby_status	String	A device's standby status			✓
device	battery_status	String	A device's battery status			✓
device	power_status	String	A device's power status			✓
device	connection_status	String	A device's connection status			✓
device	ack_offline_alarm	Boolean	Acknowledge a device offline alarm	✓
device	acknowledge_all_alarms	Boolean	Acknowledge all device/zone alarms	✓
device	reset_to_defaults	Boolean	Reset the device settings to factory defaults	✓
device	clone	Integer	Clone a device's data				✓
device	firmware	Object	Firmware version of Device			✓
device	firmware_auto_update	Boolean	Will the Device automatically update to the latest firmware version			✓	✓
device	firmware_target	Object	The firmware version the Device will install		✓	✓	✓
device	firmware_available	Array of Objects	A list of available firmware to install on the Device			✓
device	firmware_changelog	Array of Strings	A list of the changes verses the currently installed version			✓

Zone Meta Type

Property	Type	Description
zone_id	Integer	The Zone ID
is_enabled	Integer	Is the zone enabled
hide_if_disabled	Boolean	Hide the zone if disabled
add_name	String	The add name

GET

URI Mode Request URI's:

• Receive all Device data for all Devices in a user's account

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

• Receive all Device data for a specific Device

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

• Receive the alarm status of a Device

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

JSON Mode Request URI:

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

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 device object.

JSON Mode Response Properties

Parent Property	Child Property	Status	Type	Description
	device	Required	Array of Objects	The parent device object.
device	device_id	Optional	Integer	ID of Device
device	id	Optional	Integer	Unique identifier located on the Device (Serial number, etc.)
device	name	Optional	String	Name of Device
device	description	Optional	String	Short description of Device
device	timezone	Optional	String	The timezone the Device is in
device	location	Optional	Object	Contains location information for the device.
location	address	Optional	Object	Address information for Device (See Sensaphone.net API/address)
location	coordinates	Optional	Object	GPS Coordinates information for Device (See Sensaphone.net API/coordinates)
device	firmware	Optional	String	Firmware version of Device
device	default_schedule	Optional	Object	Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device	device_schedule	Optional	Object	Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device	zone	Optional	Array of Objects	Device Zone data (See Sensaphone.net API/zone)
device	offline_timeout	Optional	Integer	The number of minutes a device must be offline before it goes into alarm.
device	product	Optional	String	The name of the product type
device	modbus_ports	Optional	Array of Objects	TBD
device	zone_meta	Optional	Array ofObjects	TBD
zone_meta	zone	Optional	Zone Meta Type	TBD
zone_meta	children	Optional	Array of Zone Meta Type	TBD
device	is_offline_unack	Optional	Boolean	Whether or not an unacknowledged offline alarm exists.
device	is_online	Optional	Boolean	Whether or not the device is currently online.
device	standby_time	Optional	String	The number of minutes a device will be in standby mode.
device	standby_mode	Optional	String	A device's standby mode.
device	standby_status	Optional	String	A device's standby status
device	battery_status	Optional	String	A device's battery status
device	power_status	Optional	String	A device's power status
device	battery_value	Optional	String	A device's battery value
device	power_value	Optional	String	A device's power value
device	connection_status	Optional	String	A device's connection status
device	feature	Optional	Array of Objects	The feature linked to the account (See Sensaphone.net API/feature)
device	firmware	Optional	Object	Firmware version of Device
device	firmware_auto_update	Optional	Boolean	Will the Device automatically update to the latest firmware version
device	firmware_target	Optional	Object	The firmware version the Device will install
device	firmware_available	Optional	Array of Objects	A list of available firmware to install on the Device
device	firmware_changelog	Optional	Array of Strings	A list of the changes verses the currently installed version

Example JSON

Receive all Device information for a specific Device

• Request JSON:

{
  "acctid":987654,
  "session":"0123-4567-8901",
  "request_type":"read",
  "device": {
      "device_id":1234
     }
}

• Response JSON:

{
  "result":
  {
    "success":true,
    "code":0,
    "message":"OK"
  },
  "response": 
  {
    "device":[
     {
       "device_id": 1234,
       ...
     }
    ]
  }      
}

PUT

URI Mode Request URI's:

• Edit the description of a Device

  PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/description/{DESCRIPTION}

• Edit the name of a Device

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

JSON Mode Request URI:

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

JSON Mode Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	Integer	Session ID
	request_type	String	"update"
	device	Array of Objects	The device object.
device	device_id	Integer	ID of the device.
device	CHILD PROPERTY		Device's child properties to be edited*

*One or more device child properties below are required in addition to "device_id".

JSON Mode Response Properties

Parent Property	Child Property	Status	Type	Description
	device	Required	Array of Objects	The parent device object.
device	device_id	Optional	Integer	ID of Device
device	name	Optional	String	Name of Device
device	description	Optional	String	Short description of Device
device	timezone	Optional	String	The timezone the Device is in
device	location	Optional	Object	Contains location information for the device.
location	address	Optional	Object	Address information for Device (See Sensaphone.net API/address)
location	coordinates	Optional	Object	GPS Coordinates information for Device (See Sensaphone.net API/coordinates)
device	firmware	Optional	String	Firmware version of Device
device	default_schedule	Optional	Object	Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device	device_schedule	Optional	Object	Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device	zone	Optional	Array of Objects	Device Zone data (See Sensaphone.net API/zone)
device	offline_timeout	Optional	Integer	The number of minutes a device must be offline before it goes into alarm.
device	modbus_ports	Optional	Array of Objects	TBD
device	standby_time	Optional	String	The number of minutes a device will be in standby mode.
device	standby_mode	Optional	String	A device's standby mode.
device	clone	Optional	Integer	Destination device_id to clone this device's data to
device	feature	Optional	Array of Objects	The feature linked to the device (See Sensaphone.net API/feature)
device	firmware_auto_update	Optional	Boolean	Will the Device automatically update to the latest firmware version
device	firmware_target	Optional	Integer	The firmware version the Device will install

POST

Adding a device

The preferred method to add a new Device is to use the JSON Mode Request. If the URI Mode Request is used you will be adding a Device with only the id value (not to be confused with the device_id), all other values will be left empty until a PUT request is used. With the JSON Mode Request you can add a Device with all values defined in one step.

URI Mode Request URI:

• Add a new Device

 POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/id/{DEVICEID}

JSON Mode Request URI:

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

JSON Mode Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	Integer	Session ID
	request_type	String	"create"
	device	Array of Objects	The device object.
device	id	Integer	Unique identifier located on the Device (Serial number, etc.)

JSON Mode Response Properties

Parent Property	Child Property	Status	Type	Description
	device	Required	Array of Objects	The parent device object.
device	device_id	Optional	Integer	ID of Device
device	id	Optional	Integer	Unique identifier located on the Device (Serial number, etc.)
device	name	Optional	String	Name of Device
device	description	Optional	String	Short description of Device
device	location	Optional	Object	Contains location information for the device.
location	address	Optional	Object	Address information for Device (See Sensaphone.net API/address)
location	coordinates	Optional	Object	GPS Coordinates information for Device (See Sensaphone.net API/coordinates)
device	firmware	Optional	String	Firmware version of Device
device	default_schedule	Optional	Object	Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device	device_schedule	Optional	Object	Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device	zone	Optional	Array of Objects	Device Zone data (See Sensaphone.net API/zone)
device	offline_timeout	Optional	Integer	The number of minutes a device must be offline before it goes into alarm.
device	modbus_ports	Optional	Array of Objects	TBD

Acknowledging Alarms

URI Mode Request URI:

• Acknowledge All Alarms

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

JSON Mode Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	Integer	Session ID
	request_type	String	"create"
	device	Array of Objects	The device object.
device	device_id	Integer	ID of Device
device	ack_offline_alarm	Boolean	A write-only property that will acknowledge a device offline alarm
device	acknowledge_all_alarms	Boolean	A write-only property that will acknowledge all alarms for a device, including all device alarms and all zone alarms

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

DELETE

URI Mode Request URI:

• Delete a Device from an account

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

JSON Mode Request URI:

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

JSON Mode Request Properties

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	Integer	Session ID
	request_type	String	"delete"
	device	Array of Objects	The device object.
device	device_id	Integer	ID of the device.