Sensaphone.net - New pages [en]

FAQ

2020-11-17T02:38:35Z

Mwood: /* List Devices */

==Where's the API Documentation?==
[[Sensaphone.net API|REST API docs]]

==How do I make REST calls?==
'''All REST requests should be made against https://rest.sensaphone.net'''

We recommend the use of a REST client for developing and testing calls to our REST API. Searching for 'rest client' in your favorite search engine will turn up many suitable results.

==How do I login?==
===Overview===
To use the Sensaphone REST API, a login call must first be made. A successful login request will return an account number and a session token. These will be used in all subsequent requests. Two examples of login requests are shown below. First, the URI-mode version, followed by the JSON-mode version.

===Examples===
URI-mode:

<syntaxhighlight lang="JavaScript">
POST https://rest.sensaphone.net/api/v1/login/{myuser@example.com}/{abc123_my_password}
</syntaxhighlight>

JSON-mode:
<syntaxhighlight lang="JavaScript">
POST https://rest.sensaphone.net/api/v1/login
{
"request_type": "create",
"resource": "login",
"user_name": "myuser@example.com",
"password": "abc123_my_password"
}
</syntaxhighlight>

===Reply===
The reply to a successful login request will contain a '''result''' object and a '''response''' object. The '''result''' communicates the overall success of the call. The '''response''' contains the data in which we are interested: in this case, the account number (acctid), and the session token. The account number and session token will be used in every subsequent query submitted to the API.

<syntaxhighlight lang="JavaScript">
{
"result": {
"success": true,
"code": 0,
"message": "Success"
},
"response": {
"acctid": 21620750,
"session": "1234ffffeeee5678aaaccda609cd8fb5099",
"login_timestamp": 1605562465,
"session_expiration": 86400,
"user_id": 12345678
}
}
</syntaxhighlight>

===References===
# [[Sensaphone.net API/login|Login Resource]]: Additional information about the login resource
# [[Sensaphone.net API#Overview|URI-mode/JSON-mode]]: Information about URI-mode and JSON-mode

==How do I access log data?==
===Overview===
Queries to our logging facilities are one of the most popular uses of the Sensaphone API. Making a successful log query involves first acquiring multiple pieces of data from the API. Because of this fact, crafting your first log query will be a multi-step process. All logs are accessed through the [[Sensaphone.net_API/history|history resource]]. Outlined below you will find a practical example of how to gather the data needed to make a successful query to the history resource. We will use JSON-mode for each request as we gather the info required to query for datalogs.

If there are multiple log points within a similar time range you wish to access, it is generally more efficient to submit a request which includes all log points in which you are interested and use larger page sizes. You can then page through the results returned by the API, processing as you go. This is preferable to smaller, more frequent requests to individual log points using smaller page sizes.

===Examples===
====Datalog====
Every device (e.g. Sentinel, Sentinel Pro, Stratus) associated with an account has input zones to which sensors may be connected. A device may be configured to log the value of any input zone at specific intervals. On [https://www.sensaphone.net www.sensaphone.net] (the Website) the user may query a time range of datalog records for a single device. Users of the REST API can make similar queries against the input zones of one or more devices.

The data required to perform a datalog query are defined as follows:
; log_points/data_log_points
: List of one or more globally unique numeric ID's, each representing a "loggable" device zone.
; begin_offset
: The offset of the first record to be returned to the caller. An offset of 0 indicates the beginning of the queried timerange. Increasing this offset by 50, for example, means we return results beginning with the fiftieth record obtained by the query. Use this value to "page" through results in descending order, newest to oldest. Experiment to find an offset value that works well for your application. Works in tandem with "record_offset".
; record_offset
: Number of results to return per "page".
; start
: The greatest (most recent) [[Sensaphone.net_API/history#Timestamps|Sensaphone-encoded timestamp]] we are interested in, ''non-inclusive''. Also [[#How do I calculate Sensaphone-encoded timestamps?|see below]] for more details about how this value may be calculated.
; end
: The least (oldest) [[Sensaphone.net_API/history#Timestamps|Sensaphone-encoded timestamp]] we are interested in, ''inclusive''. Also [[#How do I calculate Sensaphone-encoded timestamps?|see below]] for more details about how this value may be calculated.

We will take the following steps to retrieve the information necessary for a query to the datalog facility:
# Get a list of devices associated with an account
# Get a list of '''log_points''' from a device
# Calculate Sensaphone-encoded '''start''' and '''end''' timestamps
# Query for datalog records
# Page through the results

For the remainder of this example, let's assume the following:
acctid = 12345678 # account_id
session = 1234aaa5678bbbb8765cccc4321dddd # session token

=====List Devices=====
First let's list all devices associated with our account and choose one from the results. To do this we will make a call to the Dashboard resource, requesting the name and device_id of each device on our account.

<syntaxhighlight lang="JavaScript">
POST https://rest.sensaphone.net/api/v1/{12345678}/{1234aaa5678bbbb8765cccc4321dddd}/dashboard
{
"request_type": "read",
"resource": "dashboard",
"dashboard": {
"device": [
{
"device_id": null,
"name": null
}
]
}
}
</syntaxhighlight>

The array of device data can be found in the '''response''' object in the server's reply. For the remainder of this example let's assume we have acquired the following device_id:
device_id = 9191

=====List Log Points=====
With a device_id of 9191 in hand, we may now query for log_points associated with that device.

<syntaxhighlight lang="JavaScript">
POST https://rest.sensaphone.net/api/v1/{12345678}/{1234aaa5678bbbb8765cccc4321dddd}/history/data_log_points
{
"request_type": "read",
"resource": "history",
"history": [
{
"data_log_points": {
"resource_type": "device",
"device_id": 9191
}
}
]
}
</syntaxhighlight>

The server's reply will contain data for each loggable zone, including input zones and output zones. The log_point value of each zone is unique across all devices. Therefore a log_point value of 78208181 will refer to one, and only one, zone. Extract log_point values for all zones to be queried.

Assume we have decided to pull datalog records for the following log points:
15144093
15145683
15148853

=====Calculate start and end timestamps=====
Calculate the '''start''' and '''end''' timestamps [[#How do I calculate Sensaphone-encoded timestamps?|as outlined here]]. The range of records returned will fall in the range ''(start, end]'', meaning records will be considered a match if the date of the record equals '''end''' all the way up to, but not including, '''start'''.

{| class="wikitable" style="border-left: 4px solid #f90; background-color: #fff8e6; width: 100%;"
|-
| '''⚠ Warning: <code>start</code> and <code>end</code> are reversed from convention.'''

In the datalog API, <code>start</code> is the '''most recent''' (newest) timestamp in your range,
and <code>end</code> is the '''oldest''' timestamp. Records are returned in descending order, newest first.
The query range is '''exclusive''' of <code>start</code> and '''inclusive''' of <code>end</code>,
expressed as the interval <code>(start, end]</code>.
|}

Let's assume we wish to query the following two dates:
start = November 18, 2020 12:30pm --> sensaphone_time(2020, 10, 17, 12, 30, 00) --> 671113800
end = November 01, 2020 12:00am --> sensaphone_time(2020, 10, 00, 00, 00, 00) --> 669600000

=====Make the request=====
Now that we have all the necessary data we can put it together and make our datalog request.

<syntaxhighlight lang="JavaScript">
POST https://rest.sensaphone.net/api/v1/{12345678}/{1234aaa5678bbbb8765cccc4321dddd}/history/data_log
{
"request_type": "read",
"resource": "history",
"history": {
"data_log": {
"log_points": [ 15144093, 15145683, 15148853 ],
"start": 671113800,
"end": 669600000,
"begin_offset": 0,
"record_offset": 1000
}
}
}
</syntaxhighlight>

Assuming records exist for those log_points during that time range, 1000 of them will be returned. Why 1000? Recall that record_offset determines the maximum number of records to be returned per request.

=====Paging through results=====
If there are more records to be reviewed, we can page through our results by making another call. This time we will increment the '''begin_offset''' by the number of records per page ('''record_offset''').

<syntaxhighlight lang="JavaScript" highlight=10>
POST https://rest.sensaphone.net/api/v1/{12345678}/{1234aaa5678bbbb8765cccc4321dddd}/history/data_log
{
"request_type": "read",
"resource": "history",
"history": {
"data_log": {
"log_points": [ 15144093, 15145683, 15148853 ],
"start": 671113800,
"end": 669600000,
"begin_offset": 1000,
"record_offset": 1000
}
}
}
</syntaxhighlight>

=====Queries against zones of multiple devices=====
Recall that zone ID's are unique across '''all''' devices. If you wish to query for datalog records on zones across multiple devices, simply acquire the log points for the zones of the devices you wish to view and make your query as we have shown above. The only difference here is that the log points used in the request represent zones across more than one device.

===Tips for Effective Datalog Requests===
# When datalog values for multiple log points are required, an efficient request will include several log points of interest over a given time range with a larger page size (record_offset). This provides more context to the API, allowing it to prefetch records as you page through your results. Avoid making flurries of requests for individual log points and/or using small page sizes where a larger more comprehensive request can be made.
# Adjust your page size (record_offset) to your use case. If performing bulk processing then prefer larger page sizes. Smaller page sizes may be preferable if you are displaying results for users to read.
# Acquire datalog values from multiple devices in the same query if the desired time ranges are compatible.
# Datalog values are not 'live' data. Polling the API repeatedly for recent datalog values will not cause them to appear faster. Datalog records are periodically uploaded to our servers in batches by each device at a set interval. The exact time at which these uploads take place is negotiated between the device and server.

===References===
* [[Sensaphone.net API/history|History]]: Documentation for the history resource.
* [[Sensaphone.net API/device|Device]]: Documentation for the device resource.
* [[Sensaphone.net API/history#Timestamps|Sensaphone Timestamps]]: Documentation for Sensaphone-encoded timestamps.
* [[Sensaphone.net API/history#Data Log Points|Data Log Points]]: Documentation for the data_log_points resource.
* [https://en.wikipedia.org/wiki/Modulo_operation Modulo (mod) operation]: Information about the modulo operation.

==How do I calculate Sensaphone-encoded timestamps?==
===Overview===
Internally, the Sensaphone API uses a custom date encoding. The only time a user of the REST API must worry about these encoded timestamps is when making requests against the [[Sensaphone.net API/history|history]] resource.

The most important thing to keep in mind when converting to Sensaphone timestamps: All data passed into the algorithm is base-0. This means that the first day of the month is not 1, but 0. Likewise January is not 1, but 0. Due to the fact that we count our minutes and seconds from 0, you will not notice a difference when passing these values into the algorithm. The same goes for the year. Where this base-0 concept will have the most noticeable impact will be ''hour of the day'', ''day of the month'', and ''month of the year''.

Observe:
* 0 - 59 seconds per minute
* 0 - 59 minutes per hour
* 0 - 23 hours per day (0 = 12am, 1, 2, ..., 23 = 11pm)
* 0 - 30 are 31-day months
* 0 - 29 are 30-day months
* 0 - 27 most Februaries
* 0 - 28 leap-year Februaries
* 0 - 11 months per year
* 2000 - ... the year

The algorithm in pseudocode:
timestamp <-- (seconds mod 60) + // 0 - 59
((minutes * 60) mod 3600) + // 0 - 59
((hours * 3600) mod 86400) + // 0 - 23
((day * 86400) mod 2678400) + // 0 - 31
((month * 2678400) mod 32140800) + // 0 - 11
((year mod 100) * 32140800) // 2000 - ...

===Implementations===
Provided below are some helpful functions to convert date and time into Sensaphone time stamps.

==== Bash ====

This implementation accepts a natural language date string and uses the
<code>date</code> program to parse it, handling base-0 conversion internally.
Both GNU <code>date</code> (Linux) and BSD <code>date</code> (macOS) are supported.
This snippet is useful if you are using cURL to make your REST calls from the command line.

<syntaxhighlight lang="bash" line>
sensaphone_time() {
local date_string="$1"

# Parse date string to Unix timestamp
# GNU date (Linux) accepts free-form strings via -d
# BSD date (macOS) requires ISO 8601 format: "YYYY-MM-DD HH:MM:SS"
if date --version &>/dev/null 2>&1; then
local unix_time=$(date -d "$date_string" +%s)
else
local unix_time=$(date -j -f "%Y-%m-%d %H:%M:%S" "$date_string" +%s)
fi

# Decompose Unix timestamp into components (day and month adjusted to base-0)
local second=$(date -d "@$unix_time" +%-S 2>/dev/null || date -r "$unix_time" +%-S)
local minute=$(date -d "@$unix_time" +%-M 2>/dev/null || date -r "$unix_time" +%-M)
local hour=$(date -d "@$unix_time" +%-H 2>/dev/null || date -r "$unix_time" +%-H)
local day=$(( $(date -d "@$unix_time" +%-d 2>/dev/null || date -r "$unix_time" +%-d) - 1 ))
local month=$(( $(date -d "@$unix_time" +%-m 2>/dev/null || date -r "$unix_time" +%-m) - 1 ))
local year=$(date -d "@$unix_time" +%Y 2>/dev/null || date -r "$unix_time" +%Y)

local sensaphone_timestamp=$(( (second % 60) +
((minute * 60) % 3600) +
((hour * 3600) % 86400) +
((day * 86400) % 2678400) +
((month * 2678400) % 32140800) +
((year % 100) * 32140800) ))

echo $sensaphone_timestamp
}
</syntaxhighlight>

Example usage:

<syntaxhighlight lang="bash" line>
# GNU date (Linux) - accepts natural language strings
sensaphone_time "November 18 2020 12:30:00" # --> 671113800
sensaphone_time "2020-11-18 12:30:00" # --> 671113800

# BSD date (macOS) - requires ISO 8601 format
sensaphone_time "2020-11-18 12:30:00" # --> 671113800
</syntaxhighlight>

==== Zsh ====
This implementation uses the <code>zsh/datetime</code> module's <code>strptime</code>
and <code>strftime</code> builtins to parse and decompose dates without invoking
an external <code>date</code> program. It accepts ISO 8601 format date strings
and handles base-0 conversion internally.

<syntaxhighlight lang="bash" line>
sensaphone_time() {
local date_string="$1"
local unix_time

# Load zsh datetime module for strptime and strftime builtins
zmodload zsh/datetime

# Parse date string to Unix timestamp using the strptime builtin.
# Accepts ISO 8601 format: "YYYY-MM-DD HH:MM:SS"
strptime -s unix_time "%Y-%m-%d %H:%M:%S" "$date_string"

# Decompose Unix timestamp into named components using strftime -s.
# strftime zero-pads values (e.g. "08"), so we use (( x + 0 )) to
# strip leading zeros before arithmetic to avoid octal interpretation.
# Day and month are adjusted to base-0 as required by the API.
local -A t
strftime -s t[second] "%S" $unix_time
strftime -s t[minute] "%M" $unix_time
strftime -s t[hour] "%H" $unix_time
strftime -s t[day] "%d" $unix_time
strftime -s t[month] "%m" $unix_time
strftime -s t[year] "%Y" $unix_time

local second=$(( t[second] + 0 ))
local minute=$(( t[minute] + 0 ))
local hour=$(( t[hour] + 0 ))
local day=$(( t[day] + 0 - 1 ))
local month=$(( t[month] + 0 - 1 ))
local year=$(( t[year] + 0 ))

echo $(( (second % 60) +
((minute * 60) % 3600) +
((hour * 3600) % 86400) +
((day * 86400) % 2678400) +
((month * 2678400) % 32140800) +
((year % 100) * 32140800) ))
}
</syntaxhighlight>

Example usage:

<syntaxhighlight lang="bash" line>
# Accepts ISO 8601 format date strings
sensaphone_time "2020-11-18 12:30:00" # --> 671113800
</syntaxhighlight>

{| class="wikitable" style="border-left: 4px solid #f90; background-color: #fff8e6; width: 100%;"
|-
| '''⚠ Note: <code>zsh/datetime</code> and timezone behavior'''

The <code>zsh/datetime</code> module is included in all standard zsh
distributions and does not require separate installation. As with the other
implementations on this page, dates are interpreted in local time. To use UTC,
set <code>TZ=UTC</code> before calling the function, or export it in your
environment.
|}

====Python====

This implementation accepts a standard <code>datetime</code> object.
Note that Python's <code>datetime.day</code> and <code>datetime.month</code>
are both 1-indexed, so both are adjusted to base-0 internally.

<syntaxhighlight lang="python" line>
from datetime import datetime

def sensaphone_time(dt):
return (dt.second % 60) + \
( (dt.minute * 60) % 3600) + \
( (dt.hour * 3600) % 86400) + \
(((dt.day - 1) * 86400) % 2678400) + \
(((dt.month - 1) * 2678400) % 32140800) + \
( (dt.year % 100) * 32140800)
</syntaxhighlight>

Example usage:

<syntaxhighlight lang="python" line>
# November 18, 2020 12:30pm (local time)
dt = datetime(2020, 11, 18, 12, 30, 0)
print(sensaphone_time(dt)) # --> 671113800
</syntaxhighlight>

==== PHP ====

This implementation accepts a standard <code>DateTime</code> object.
PHP's <code>DateTime</code> uses 1-indexed days and months, so both
are adjusted to base-0 internally.

<syntaxhighlight lang="php" line>
<?php
function sensaphone_time(DateTime $dt): int {
$second = (int)$dt->format('s');
$minute = (int)$dt->format('i');
$hour = (int)$dt->format('G');
$day = (int)$dt->format('j') - 1;
$month = (int)$dt->format('n') - 1;
$year = (int)$dt->format('Y');

return ($second % 60) +
(($minute * 60) % 3600) +
(($hour * 3600) % 86400) +
(($day * 86400) % 2678400) +
(($month * 2678400) % 32140800) +
(($year % 100) * 32140800);
}
?>
</syntaxhighlight>

Example usage:

<syntaxhighlight lang="php" line>
<?php
// November 18, 2020 12:30pm (local time)
$dt = new DateTime('2020-11-18 12:30:00');
echo sensaphone_time($dt); // --> 671113800
?>
</syntaxhighlight>

====JavaScript====

This implementation accepts a standard JavaScript <code>Date</code> object,
handling the base-0 conversion for day-of-month internally. It is compatible
with both browser environments and Node.js.

<syntaxhighlight lang="JavaScript" line>
function sensaphoneTime(date) {
return ( date.getSeconds() % 60) +
( (date.getMinutes() * 60) % 3600) +
( (date.getHours() * 3600) % 86400) +
(((date.getDate() - 1) * 86400) % 2678400) + // Note: We must subtract 1!
( (date.getMonth() * 2678400) % 32140800) +
( (date.getFullYear() % 100) * 32140800);
}
</syntaxhighlight>

Example usage:

<syntaxhighlight lang="javascript" line>
// November 18, 2020 12:30pm (local time)
const date = new Date(2020, 10, 18, 12, 30, 0);
sensaphoneTime(date); // --> 671113800
</syntaxhighlight>

===References===
* [[Sensaphone.net API/history#Timestamps|Sensaphone-encoded timestamps]]: More info regarding timestamp encoding
* [https://en.wikipedia.org/wiki/Modulo_operation Modulo (mod) operation]: Information about the modulo operation.

Sensaphone.net API/feature

2015-05-28T13:58:40Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=
==Specifications==
The feature resource

The feature resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | feature | Array of Object | The feature linked to the account/device | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| feature | feature_id | Integer | The ID of the feature | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| feature | resource | String | The resource of the feature | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| feature | description | String | The description of the feature | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| feature | resource_id | Integer | The ID of the resource | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| feature | parent_ids | Array of Integers | The IDs of the parent features | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| feature | option | String | The value of the feature | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| feature | is_hidden | Boolean | Is the feature hidden | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableEnd}}

===GET===
'''URI Mode Request URI's:'''
*Retrieve all the account features
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/account/feature

*Retrieve all the device features
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/feature

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/account/feature

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Properties''' | '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN| ''<parent>'' | feature | Array of Objects | The features object
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | feature | Required | Object | The feature linked to the account/device
}}{{TableRowN| feature | feature_id | Required | Integer | The ID of the feature
}}{{TableRowN| feature | resource | Optional | String | The resource of the feature
}}{{TableRowN| feature | description | Optional | String | The description of the feature
}}{{TableRowN| feature | resource_id | Optional | Integer | The ID of the resource
}}{{TableRowN| feature | parent_ids | Optional | Array of Integers | The IDs of the parent features
}}{{TableRowN| feature | option | Optional | String | The value of the feature
}}{{TableRowN| feature | is_hidden | Optional | Boolean | Is the feature hidden
}}{{TableEnd}}

====Example JSON====
Receive all the account features' option

*'''Request JSON:'''
{
"acctid": 987654,
"sessionid": "0123-4567-8901",
"request_type": "read",
"account": [
{
"option" : null
}
]
}

*'''Response JSON'''
{
"result":
{
"success": true,
"code": 0,
"message": "OK"
},
"response":
{
"account": [
{
"feature": [
{
"feature_id" : 1234,
"option" : "Premium"
}
]
}]
}
}

===PUT===
'''URI Mode Request URI's:'''
*Change an account feature
'''PUT''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SEESIONID}/account/feature/option/{NEW_OPTION}

'''JSON Mode Request URI:'''
'''POST''' https://rest.sensaphone.net/api/v1/account/feature
'''POST''' https://rest.sensaphone.net/api/v1/device/feature

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Properties''' | '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN| ''<parent>'' | feature | Array of Objects | The feature object
}}{{TableRowN| feature | '''''CHILD PROPERTY''''' |   | Feature's child properties to be edited*
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | feature | Optional | Object | The feature linked to the account/device
}}{{TableRowN| feature | feature_id | Required | Integer | The ID of the feature
}}{{TableRowN| feature | option | Optional | String | The value of the feature
}}{{TableEnd}}

Sensaphone.net API/contact

2015-04-29T19:26:06Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=
The Destination object contains the information needed for alarm notifications to a [[Sensaphone.net API/user|'''User''']], [[Sensaphone.net API/calllist|'''Call Lists''']], and/or [[Sensaphone.net API/alarmschedule|'''Alarm Schedule''']].

==Specifications==
*A contact is its own API resource. It represents a single destination for alarm delivery. The resource will be used for creating, adding, and editing both user dependent and independent contacts in Call List or Alarm Schedule. In addition, a contact object can be accessed from other API resources such as [[Sensaphone.net API/user|'''User''']] and [[Sensaphone.net API/contactgroup|'''Contact Group''']].

The contact resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | contact | Object | The contact object. | '''✓''' | '''✓''' | '''✓''' | '''n/a'''
}}{{TableRowN| contact | contact_id | Integer | ID of the contact. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| contact | destination | String | The destination. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| contact | type | String | The destination's type. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| contact | description | String | The destination's description. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| contact | enable | Boolean | If the contact is enabled. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| contact | schedule | Object | (See [[Sensaphone.net API/schedule|Sensaphone.net API/schedule]]) | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableEnd}}

===GET===
'''URI Mode Request URI's:'''
*Retrieve all information for all of a user's contacts.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact
*Retrieve the description of a specific user's contact.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact/{CONTACT_ID}/description
*Retrieve all of the contact IDs for a particular user's contacts.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact/contact_id

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/user/alarm_user/contact

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "contact" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | contact | Array of Objects | The contact object
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | contact | Required | Array of Objects | The contact object
}}{{TableRowN| contact | contact_id | Optional | Integer | ID for contact
}}{{TableRowN| contact | type | Optional | String | Phone, SMS or Email (Use a V2 [[Sensaphone.net_API/contact#GET|read command]] to retrieve the valid values)
}}{{TableRowN| contact | destination | Optional | String | Phone number, Email address, etc. of contact's destination
}}{{TableRowN| contact | description | Optional | String | Short description describing the destination ex: "Work Phone"
}}{{TableRowN| contact | schedule | Optional | Object | (See [[Sensaphone.net API/schedule|Sensaphone.net API/schedule]])
}}{{TableRowN| contact | enable | Optional | Boolean | If the contact is enabled.
}}{{TableEnd}}

====Example JSON====
Retrieve all the contact information for a particular user.
*'''Request JSON'''

{
"acctid":987654,
"session":"0123-4567-8901",
"request_type":"read",
"user": [ { ← "user" is a parent object
"user_id":395,
"alarm_user" : {
"contact": null ← On a "read", a null property can be used to retrieve all instances of that property.
}
} ]
}

*'''Response JSON'''

{
"result":
{
"success":true,
"code":0,
"message":"OK"
}
"response":
{
"user":[
{
"alarm_user": {
"user_id":395,
"contact":[
{
"contact_id":0001,
"type":"Phone",
"destination":"555 555 5555",
"description": "Work Phone",
"enable": true,
"schedule":{
"schedule_id": 345567,
... ← See [[Sensaphone.net API/schedule|here]] for schedule object specification
}
},
{
"contact_id":0002,
"type":"SMS",
"destination":"555 555 5555",
"description": "Cell Phone"
"enable": true,
"schedule":{
"schedule_id": 412571,
...
}
},
{
"contact_id":0003,
"type":"Email",
"destination":"johndoe@sensaphone.net",
"description": "Work Email"
"enable": true,
"schedule":{
"schedule_id": 567437,
...
}
}
]
}
}
]
}
}

===PUT===
'''URI Mode Request URI's'''
*Edit the '''description''' of a contact
'''PUT''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact/{CONTACT_ID}/description/{DESCRIPTION}
*Edit the '''destination''' of a contact
'''PUT''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact/{CONTACT_ID}/destination/{DESTINATION}
*Edit the contact's destination '''type'''
'''PUT''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact/{CONTACT_ID}/type/{TYPE}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/user/alarm_user/contact

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "update"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "contact" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | contact | Array of Objects | The contact object
}}{{TableRowN| contact | contact_id | Integer | ID for contact
}}{{TableRowN| contact | '''''CHILD PROPERTY''''' |   | Child properties to be edited *
}}{{TableEnd}}
<nowiki>*</nowiki> One or more '''contact''' child properties listed below are required in addition to "contact_id".

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | contact | Required | Array of Objects | The contact object
}}{{TableRowN| contact | contact_id | Optional | Integer | ID for contact
}}{{TableRowN| contact | type | Optional | String | Phone, SMS or Email (Use a V2 [[Sensaphone.net_API/contact#GET|read command]] to retrieve the valid values)
}}{{TableRowN| contact | destination | Optional | String | Phone number, Email address, etc. of contact's destination
}}{{TableRowN| contact | description | Optional | String | Short description describing the destination ex: "Work Phone"
}}{{TableRowN| contact | schedule | Optional | Object | (See [[Sensaphone.net API/schedule|Sensaphone.net API/schedule]])
}}{{TableRowN| contact | enable | Optional | Boolean | If the contact is enabled.
}}{{TableEnd}}

===POST===
POST will only be used for creating a new contact. The destination (phone number or email address) is required and the type automatically determined. If using the URI Mode Request the user can subsequently use PUT to edit the other sub-properties and/or change the type. Alternatively, this can be done in one step with the JSON Mode Request.

'''URI Mode Request URI:'''
*Create a new user dependent contact.
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact/destination/{DESTINATION}
*Create a new user independent contact.
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contact/destination/{DESTINATION}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/user/alarm_user/contact

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "contact" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | contact | Array of Objects | The contact object
}}{{TableRowN| contact | destination | String | Phone number or Email address of Destination
}}{{TableRowN| contact | '''''CHILD PROPERTY''''' |   | Additional child properties to be set *
}}{{TableEnd}}
<nowiki>*</nowiki> One or more '''contact''' child properties listed below ''may'' be specified in addition to "contact_id" and "destination".

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | contact | Required | Array of Objects | The contact object
}}{{TableRowN| contact | contact_id | Optional | Integer | ID for contact
}}{{TableRowN| contact | type | Optional | String | Phone, SMS or Email (Use a V2 [[Sensaphone.net_API/contact#GET|read command]] to retrieve the valid values)
}}{{TableRowN| contact | destination | Optional | String | Phone number, Email address, etc. of contact's destination
}}{{TableRowN| contact | description | Optional | String | Short description describing the destination ex: "Work Phone"
}}{{TableRowN| contact | schedule | Optional | Object | (See [[Sensaphone.net API/schedule|Sensaphone.net API/schedule]])
}}{{TableRowN| contact | enable | Optional | Boolean | If the contact is enabled.
}}{{TableEnd}}

===DELETE===
'''URI Mode Request URI:'''
*Delete a contact. To delete a contact, the ID of the contact to be deleted must be provided.
'''DELETE''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact/{CONTACT_ID}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/user/alarm_user/contact

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "delete"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "contact" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | contact | Array of Objects | The contact object
}}{{TableRowN| contact | contact_id | Integer | ID for contact
}}{{TableEnd}}

Sensaphone.net API/user

2015-04-29T19:24:08Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=

==Specifications==
The '''user''' resource allows access to information relating to two classes of persons: those who will have access to the website and API and those who will be notified in the event of an alarms. A user may be in one, both, or neither class.

The user resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | user | Object | The user object. | '''✓''' | '''✓''' | '''✓''' | '''n/a'''
}}{{TableRowN| user | user_id | Integer | ID of the user. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| user | name | String | Name of user. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| user | enable | Boolean | If the user is enabled. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| user | alarm_user_mode | String | The alarm user mode | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| user | site_user_level | String | The site user access level | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| user | is_site_user | Boolean | If the user has site access (website or API) | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| user | site_user | Object | sub-object contains data for where is_site_user is 'true'. Is still accessed using the "user" resource | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| site_user | devices | Array of String | List of devices (device_guid) accessible by this user. | '''✓''' | '''✓''' | '''✓''' | ''' '''
}}{{TableRowN| site_user | groups | Array of Integer | group IDs of the groups accessible by this user. | '''✓''' | '''✓''' | '''✓''' | ''' '''
}}{{TableRowN| site_user | username | String | The username to access the website or API | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| site_user | access_level | String | The current access level for website or API access. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| site_user | address | Object | (See [[Sensaphone.net API/address|Sensaphone.net API/address]]) | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| user | is_alarm_user | Boolean | If the user is enabled for alarm delivery. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| user | alarm_user | Object | sub-object contains data for where is_alarm_user is 'true'. Is still accessed using the "user" resource. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| alarm_user | schedule | Object | (See [[Sensaphone.net API/schedule|Sensaphone.net API/schedule]]) | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| alarm_user | contact | Array of Object | (See [[Sensaphone.net API/contact|Sensaphone.net API/contact]]) | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableEnd}}

===GET===
'''URI Request Mode URI's:'''
*Retrieve all user data for all users in the account.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{''ACCTID''}/{''SESSIONID''}/user
*Retrieve all user data for a specific user.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{''ACCTID''}/{''SESSIONID''}/user/{''USER_ID''}
*Retrieve the name of a specific user.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{''ACCTID''}/{''SESSIONID''}/user/{''USER_ID''}/name
'''JSON Request Mode URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/user

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "user" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | user | Array of Objects | The user object
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | user | Required | Array of Objects | The user object
}}{{TableRowN| user | user_id | Optional | Integer | ID of user
}}{{TableRowN| user | name | Optional | String | Name of user
}}{{TableRowN| user | enable | Optional | Boolean | If the user is enabled.
}}{{TableRowN| user | alarm_user_mode | Optional | String | The alarm user mode.
}}{{TableRowN| user | site_user_level | Optional | String | The site user access level
}}{{TableRowN| user | is_site_user | Optional | Boolean | If the user has site access (website or API)
}}{{TableRowN| user | site_user | Optional | Object | sub-object contains data for where is_site_user is 'true'. Is still accessed using the "user" resource.
}}{{TableRowN| site_user | devices | Optional | Array of String | List of devices (device_guid) accessible by this user.
}}{{TableRowN| site_user | groups | Optional | Array of Integer | group IDs of the groups accessible by this user.
}}{{TableRowN| site_user | username | Optional | String | The username to access the website or API
}}{{TableRowN| site_user | access_level | Optional | String | The current access level for website or API access.
}}{{TableRowN| site_user | address | Optional | Object | (See [[Sensaphone.net API/address|Sensaphone.net API/address]])
}}{{TableRowN| user | is_alarm_user | Optional | Boolean | If the user is enabled for alarm delivery.
}}{{TableRowN| user | alarm_user | Optional | Object | sub-object contains data for where is_alarm_user is 'true'. Is still accessed using the "user" resource.
}}{{TableRowN| alarm_user | schedule | Optional | Object | (See [[Sensaphone.net API/schedule|Sensaphone.net API/schedule]])
}}{{TableRowN| alarm_user | contact | Optional | Array of Objects | (See [[Sensaphone.net API/contact|Sensaphone.net API/contact]])
}}{{TableEnd}}

====Example JSON====
Receive all User information
* '''Request JSON:'''

{
"request_type":"read",
"resource":"user",
"acctid":987654,
"session":"0123-4567-8901",
"user": null ← On a "read", a null property can be used to retrieve all instances of that property.
}

* '''Response JSON:'''
{
"result":
{
"success":true.
"code":0,
"message":"OK",
},
"response":
{
"user":[
{
"user_id": 1010
"name": "John Doe",
"enable": true,
"is_site_user": true,
"site_user": {
"devices": [
"00-11-22-33-44-55",
"AA-BB-CC-DD-EE-FF"
],
"groups": [
12345,
85693
],
"username": "jdoe@example.net",
"access_level": "Admin",
"address":{
... ← See [[Sensaphone.net API/address|here]] for address object specification
}
},
"is_alarm_user": true,
"alarm_user": {
"schedule":{
... ← See [[Sensaphone.net API/schedule|here]] for schedule object specification
},
"contact":[
{
"contact_id": 1201,
... ← See [[Sensaphone.net API/contact|here]] for contact object specification
},
{
"contact_id": 1202,
...
},
{
"contact_id": 1203,
...
}
]
}
},
{
"user_id": 1023
... ← More than one user is returned because a "null" user was requested.
}
]
}
}

===PUT===
'''URI Mode Request URI's:'''
*Edit a user's '''name''' value
'''PUT''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/name/{NAME}
'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/user

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "update"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "user" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | user | Array of Objects | The user object
}}{{TableRowN| user | user_id | Integer | ID for user
}}{{TableRowN| user | '''''CHILD PROPERTY''''' |   | User's child properties to be edited*
}}{{TableEnd}}
<nowiki>*</nowiki>One or more '''user''' child properties listed below are required in addition to "user_id".

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | user | Required | Array of Objects | The user object
}}{{TableRowN| user | user_id | Optional | Integer | ID of user
}}{{TableRowN| user | name | Optional | String | Name of user
}}{{TableRowN| user | enable | Optional | Boolean | If the user is enabled.
}}{{TableRowN| user | alarm_user_mode | Optional | String | The alarm user mode.
}}{{TableRowN| user | site_user_level | Optional | String | The site user access level
}}{{TableRowN| user | is_site_user | Optional | Boolean | If the user has site access (website or API)
}}{{TableRowN| user | site_user | Optional | Object | sub-object contains data for where is_site_user is 'true'. Is still accessed using the "user" resource.
}}{{TableRowN| site_user | devices | Optional | Array of String | List of devices (device_guid) accessible by this user.
}}{{TableRowN| site_user | groups | Optional | Array of Integer | group IDs of the groups accessible by this user.
}}{{TableRowN| site_user | username | Optional | String | The username to access the website or API
}}{{TableRowN| site_user | password | Optional | String | The password to access the website or API
}}{{TableRowN| site_user | access_level | Optional | String | The current access level for website or API access.
}}{{TableRowN| site_user | address | Optional | Object | (See [[Sensaphone.net API/address|Sensaphone.net API/address]])
}}{{TableRowN| user | is_alarm_user | Optional | Boolean | If the user is enabled for alarm delivery.
}}{{TableRowN| user | alarm_user | Optional | Object | sub-object contains data for where is_alarm_user is 'true'. Is still accessed using the "user" resource.
}}{{TableRowN| alarm_user | schedule | Optional | Object | (See [[Sensaphone.net API/schedule|Sensaphone.net API/schedule]])
}}{{TableRowN| alarm_user | contact | Optional | Array of Objects | (See [[Sensaphone.net API/contact|Sensaphone.net API/contact]])
}}{{TableEnd}}

===POST===
The preferred method to create a new User is to use the JSON Mode Request. If the URI Mode Request is used you will be adding a User with only the '''name''' value, all other values will be left empty until a PUT request is used. With the JSON Mode Request you can create a User with all values defined in one step.

'''URI Mode Request URI:'''
*Create a new User
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/name/{NAME}
'''JSON Mode Request URI'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/user

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "user" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | user | Array of Objects | The user object
}}{{TableRowN| user | name | String | Name of user
}}{{TableRowN| user | '''''CHILD PROPERTY''''' |   | Additional child properties to be set*
}}{{TableEnd}}
<nowiki>*</nowiki>One or more '''user''' child properties listed below ''may'' be specified in addition to "user_id" and "name".

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | user | Required | Array of Objects | The user object
}}{{TableRowN| user | user_id | Optional | Integer | ID of user
}}{{TableRowN| user | name | Optional | String | Name of user
}}{{TableRowN| user | enable | Optional | Boolean | If the user is enabled.
}}{{TableRowN| user | alarm_user_mode | Optional | String | The alarm user mode.
}}{{TableRowN| user | is_site_user | Optional | Boolean | If the user has site access (website or API)
}}{{TableRowN| user | site_user | Optional | Object | sub-object contains data for where is_site_user is 'true'. Is still accessed using the "user" resource.
}}{{TableRowN| site_user | devices | Optional | Array of String | List of devices (device_guid) accessible by this user.
}}{{TableRowN| site_user | groups | Optional | Array of Integer | group IDs of the groups accessible by this user.
}}{{TableRowN| site_user | username | Optional | String | The username to access the website or API
}}{{TableRowN| site_user | password | Optional | String | The password to access the website or API
}}{{TableRowN| site_user | access_level | Optional | String | The current access level for website or API access.
}}{{TableRowN| site_user | address | Optional | Object | (See [[Sensaphone.net API/address|Sensaphone.net API/address]])
}}{{TableRowN| user | is_alarm_user | Optional | Boolean | If the user is enabled for alarm delivery.
}}{{TableRowN| user | alarm_user | Optional | Object | sub-object contains data for where is_alarm_user is 'true'. Is still accessed using the "user" resource.
}}{{TableRowN| alarm_user | schedule | Optional | Object | (See [[Sensaphone.net API/schedule|Sensaphone.net API/schedule]])
}}{{TableRowN| alarm_user | contact | Optional | Array of Objects | (See [[Sensaphone.net API/contact|Sensaphone.net API/contact]])
}}{{TableEnd}}

===DELETE===
'''URI Mode Request URI's:'''
*Delete a User
'''DELETE''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/user

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "delete"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "user" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | user | Array of Objects | The user object
}}{{TableRowN| user | user_id | Integer | ID for user
}}{{TableEnd}}

Sensaphone.net API/contactgroup

2015-04-29T19:23:39Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=
The contactgroup object contains groupings of '''[[Sensaphone.net API/contact|contacts]]''' and '''[[Sensaphone.net API/user|users]]''' (and thus the contacts that they contain).

==Specifications==
contactgroups are both top level resources (accessed directly) and are contained as part of the alarm delivery targets contained in [[Sensaphone.net API/alarmschedule|alarm schedules]]. All groups can be manipulated directly by their ID, regardless of whether or not they are contained in other resources.

For example, say a contactgroup is part of an alarm schedule. If you "delete" the contactgroup as part of the alarm schedule (<nowiki>https://</nowiki>rest.sensaphone.net/api/v1/alarmschedule/.../contactgroup/), this would only remove it from the schedule. If you "delete" the contactgroup directly, it will remove all instances of it from every resource it is used in.

The contact group resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' | '''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | contactgroup | Object | The contactgroup object. | '''✓''' | '''✓''' | '''✓''' | '''n/a'''
}}{{TableRowN| contactgroup | group_id | Integer | ID of the contact group. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| contactgroup | name | String | The name of this group. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| contactgroup | contacts | Array of Objects | The list of contacts in this group. | '''✓''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| contacts | contact_id | Integer | The contact_id of a [[Sensaphone.net API/contact|contact]] that is a member of this group. | '''✓''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| contactgroup | users | Array of Objects | The list of groups in this group. | '''✓''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| users | user_id | Integer | The user_id of a [[Sensaphone.net API/user|user]] that is a member of this group. | '''✓''' | ''' ''' | '''✓''' | ''' '''
}}{{TableEnd}}

===GET===
'''URI Mode Response URI's:'''
*Receive all Contact Group information
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup

*Receive all Contact IDs in a given Contact Group
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/contacts/

'''JSON Mode Response URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/contactgroup

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | contactgroup | Array of Objects | The contactgroup object.
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | contactgroup | Required | Array of Objects | The parent device object.
}}{{TableRowN| contactgroup | group_id | Optional | Integer | ID of Device
}}{{TableRowN| contactgroup | name | Optional | String | The name of this group.
}}{{TableRowN| contactgroup | contacts | Optional | Array of Objects | The list of contacts in this group.
}}{{TableRowN| contacts | contact_id | Optional | Integer | The contact_id of a [[Sensaphone.net API/contact|contact]] that is a member of this group.
}}{{TableRowN| contactgroup | users | Optional | Array of Objects | The list of users in this group.
}}{{TableRowN| users | user_id | Optional | Integer | The user_id of a [[Sensaphone.net API/user|user]] that is a member of this group.
}}{{TableEnd}}

====Example JSON====
Receive all Contact Group information

*'''Request JSON:'''
{
"acctid": 987654,
"session": "0123-4567-8901",
"request_type": "read",
"contactgroup": null
}

*'''Response JSON:'''
{
"result":
{
"success": true,
"code: 0,
"message": "OK",
}
"response":
{
"contactgroup":[
{
"group_id": 6575,
"name": "Night Crew",
"users":
[
{ "user_id": 1234 },
{ "user_id": 1235 }
],
"contacts":
[
{ "contact_id": 8575 },
{ "contact_id": 8404 }
]
},
{
"group_id": 6596,
"name": "Day Crew",
"users":
[
{ "user_id": 1433 },
{ "user_id": 1531 }
],
"contacts":
[
{ "contact_id": 7523 },
{ "contact_id": 6811 }
]
}
]
}
}

===PUT===
The '''PUT''' request for the contact group resource is used to edit the group:
* Change the name

'''URI Mode Response URI:'''
*Edit a the group name
'''PUT''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/name/{GROUP_NAME}

'''JSON Mode Response URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/contactgroup

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "update"
}}{{TableRowN|   | contactgroup | Array of Objects | The contactgroup object.
}}{{TableRowN| contactgroup | group_id | Integer | ID of Device
}}{{TableRowN| contactgroup | '''''CHILD PROPERTY''''' |   | Child properties to be edited *
}}{{TableEnd}}
<nowiki>*</nowiki> One or more '''contactgroup''' child properties listed below are required in addition to "group_id".

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | contactgroup | Required | Array of Objects | The parent device object.
}}{{TableRowN| contactgroup | group_id | Optional | Integer | ID of Device
}}{{TableRowN| contactgroup | name | Optional | String | The name of this group.
}}{{TableRowN| contactgroup | contacts | Optional | Array of Objects | The list of contacts in this group.
}}{{TableRowN| contacts | contact_id | Optional | Integer | The contact_id of a [[Sensaphone.net API/contact|contact]] that is a member of this group.
}}{{TableRowN| contactgroup | users | Optional | Array of Objects | The list of users in this group.
}}{{TableRowN| users | user_id | Optional | Integer | The user_id of a [[Sensaphone.net API/user|user]] that is a member of this group.
}}{{TableEnd}}

===POST===
The preferred method to create a new Contact Group is to use the JSON Mode Request. If the URI Mode Request is used you will be adding a Contact Group with only the '''group_name''' value, all other values will be left empty until separate POST requests are used. With the JSON Mode Request you can create a Contact Group with all values defined in one step.

'''URI Mode Response URI's:'''
*Create a new Contact Group
:'''Note:''' A '''group_name''' is required when creating a new Contact Group.
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/name/{GROUP_NAME}

*Add an existing user to a Contact Group
:'''Note:''' The '''user_id''' used should be the one received in a [[Sensaphone.net API/user|user]] resource GET response.
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/users/user_id/{USER_ID}

*Add an existing contact to Contact Group
:'''Note:''' The '''contact_id''' used should be the one received in a [[Sensaphone.net API/contact|contact]] resource GET response.
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/contacts/contact_id/{CONTACT_ID}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup

'''JSON Mode Request Properties'''
:''Create new contact group''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | contactgroup | Array of Objects | The contactgroup object.
}}{{TableRowN| contactgroup | name | String | The name of this group.
}}{{TableEnd}}

: ''Add user or contact''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | contactgroup | Array of Objects | The contactgroup object.
}}{{TableRowN| contactgroup | group_id | Integer | ID of Device
}}{{TableRowN| contactgroup | contacts | Array of Objects | The list of contacts in this group.
}}{{TableRowN| contacts | contact_id | Integer | The contact_id of a [[Sensaphone.net API/contact|contact]] that is a member of this group.
}}{{TableRowN| contactgroup | users | Array of Objects | The list of users in this group.
}}{{TableRowN| users | user_id | Integer | The user_id of a [[Sensaphone.net API/user|user]] that is a member of this group.
}}{{TableEnd}}

'''JSON Mode Response Properties'''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | contactgroup | Required | Array of Objects | The parent device object.
}}{{TableRowN| contactgroup | group_id | Optional | Integer | ID of Device
}}{{TableRowN| contactgroup | name | Optional | String | The name of this group.
}}{{TableRowN| contactgroup | contacts | Optional | Array of Objects | The list of contacts in this group.
}}{{TableRowN| contacts | contact_id | Optional | Integer | The contact_id of a [[Sensaphone.net API/contact|contact]] that is a member of this group.
}}{{TableRowN| contactgroup | users | Optional | Array of Objects | The list of users in this group.
}}{{TableRowN| users | user_id | Optional | Integer | The user_id of a [[Sensaphone.net API/user|user]] that is a member of this group.
}}{{TableEnd}}

===DELETE===
'''URI Mode Request URI's:'''
*Delete a Contact Group
'''DELETE''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}

*Delete a user from a Contact Group
'''DELETE''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/users/user_id/{USER_ID}

*Delete a contact from a Contact Group
'''DELETE''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/contacts/contact_id/{CONTACT_ID}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/contactgroup

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "delete"
}}{{TableRowN|   | devicegroup | Array of Objects | The devicegroup object.
}}{{TableRowN| contactgroup | group_id | Integer | ID of Device
}}{{TableRowN| contactgroup | contacts | Array of Objects | The list of contacts in this group.
}}{{TableRowN| contacts | contact_id | Integer | The contact_id of a [[Sensaphone.net API/contact|contact]] that is a member of this group.
}}{{TableRowN| contactgroup | users | Array of Objects | The list of users in this group.
}}{{TableRowN| users | user_id | Integer | The user_id of a [[Sensaphone.net API/user|user]] that is a member of this group.
}}{{TableEnd}}

Sensaphone.net API/timerange

2015-04-29T19:22:58Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=
==Specifications==
The schedule resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | timerange | Array of Objects | The schedule's time ranges | '''✓''' | '''✓''' | '''✓''' | '''n/a'''
}}{{TableRowN| timerange | range_id | Integer | ID of the time range. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| timerange | start | String | The start time | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| timerange | end | String | The end time | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| timerange | interval | Integer (Bitmap) | Time interval options (see table) | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableEnd}}

The interval is a bitmap containing the following options. "Bit 1" is the low-order bit in the '''interval''' unsigned integer. The default value "Sunday + Monday + Tuesday + Wednesday + Thursday + Friday + Saturday", matches every day that matches the "start" and "end".
{{TableStart|border_size=1
}}{{TableRowN| '''Bit Position''' | '''Description'''
}}{{TableRowN| 1 | Timestamp: Sunday
}}{{TableRowN| 2 | Timestamp: Monday
}}{{TableRowN| 3 | Timestamp: Tuesday
}}{{TableRowN| 4 | Timestamp: Wednesday
}}{{TableRowN| 5 | Timestamp: Thursday
}}{{TableRowN| 6 | Timestamp: Friday
}}{{TableRowN| 7 | Timestamp: Saturday
}}{{TableRowN| 8 | Datetime: Is a holiday
}}{{TableRowN| 9 | Datetime: Interpret "start" and "end" as a datetime not a timestamp.
}}{{TableRowN| 10 | Datetime: Repeat: Daily
}}{{TableRowN| 11 | Datetime: Repeat: Weekly
}}{{TableRowN| 12 | Datetime: Repeat: Yearly (Day Number)
}}{{TableRowN| 13 | Datetime: Repeat: Yearly (Day of Week)
}}{{TableRowN| 14 | Invert selection. The timerange represents a time NOT selected.
}}{{TableRowN| 15 | Reserved
}}{{TableEnd}}

===GET===
'''URI Mode Request URI's:'''
*Retrieve all information for all of a schedule's timeranges.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/contact/{CONTACT_ID}/schedule/{SCHEDULE_ID}/timerange

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/user/contact/schedule/timerange

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "timerange" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | timerange | Array of Objects | The timerange object
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | timerange | Required | Array of Objects | The timerange object
}}{{TableRowN| timerange | range_id | Optional | Integer | ID for timerange
}}{{TableRowN| timerange | start | Optional | String | The start time
}}{{TableRowN| timerange | end | Optional | String | The end time
}}{{TableRowN| timerange | interval | Optional | Integer (Bitmap) | Time interval options (see table)
}}{{TableEnd}}

====Example JSON====
Retrieve time range information.

*'''Request JSON'''

{
"acctid": 987654,
"uuid": "0123-4567-8901",
"request_type": "read",
"device":[
{
"device_id": 1234,
"default_schedule":[
{
"schedule_id":28487,
"timerange": null
}
]
}
]
}

*'''Response JSON'''
{
"result":
{
"success": true,
"code": 0,
"message": "OK"
},
"response":
{
"device":[
{
"device_id": 1234,
"default_schedule":[
{
"schedule_id":28487,
"timerange":[
{
"range_id": 58381
"start": "..TBD..",
"end": "..TBD..",
"interval": 127
},
{
"range_id": 51587
"start": "..TBD..",
"end": "..TBD..",
"interval": 7
}
]
}
]
}
]
}
}

===PUT===
'''URI Mode Request URI's'''
*Edit the '''interval''' of a time range
'''PUT''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/default_schedule/{SCHEDULE_ID}/timerange/{RANGE_ID}/interval/{INTERVAL}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device/default_schedule/timerange

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "update"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "timerange" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | timerange | Array of Objects | The timerange object
}}{{TableRowN| timerange | range_id | Integer | ID for time range
}}{{TableRowN| timerange | '''''CHILD PROPERTY''''' |   | Child properties to be edited *
}}{{TableEnd}}
<nowiki>*</nowiki> One or more '''timerange''' child properties listed below are required in addition to "range_id".

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | timerange | Required | Array of Objects | The timerange object
}}{{TableRowN| timerange | range_id | Optional | Integer | ID for timerange
}}{{TableRowN| timerange | start | Optional | String | The start time
}}{{TableRowN| timerange | end | Optional | String | The end time
}}{{TableRowN| timerange | interval | Optional | Integer (Bitmap) | Time interval options (see table)
}}{{TableEnd}}

===POST===
'''URI Mode Request URI's'''
*Create a new time range with default values.
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/default_schedule/{SCHEDULE_ID}/timerange

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device/default_schedule/timerange

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "timerange" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | timerange | Array of Objects | The timerange object
}}{{TableRowN| timerange | '''''CHILD PROPERTY''''' |   | Child properties to be set *
}}{{TableEnd}}
<nowiki>*</nowiki> One or more '''timerange''' child properties below ''may'' be specified in addition to "range_id".

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | timerange | Required | Array of Objects | The timerange object
}}{{TableRowN| timerange | range_id | Optional | Integer | ID for timerange
}}{{TableRowN| timerange | start | Optional | String | The start time
}}{{TableRowN| timerange | end | Optional | String | The end time
}}{{TableRowN| timerange | interval | Optional | Integer (Bitmap) | Time interval options (see table)
}}{{TableEnd}}

===DELETE===
'''URI Mode Request URI's'''
*Create a new time range with default values.
'''DELETE''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/default_schedule/{SCHEDULE_ID}/timerange/{RANGE_ID}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device/default_schedule/timerange

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "delete"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "timerange" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | timerange | Array of Objects | The timerange object
}}{{TableRowN| timerange | range_id | Integer | ID for time range
}}{{TableEnd}}

Sensaphone.net API/schedule

2015-04-29T19:22:32Z

Mwood: /* Sensaphone.net API */ Update Session data type.

Sensaphone.net API/alarmschedule

2015-04-29T19:21:47Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=

==Access==
Alarm Schedule is not an individual API resource. However, the alarmschedule object can be accessed from the [[Sensaphone.net API/device|Device]] resource.

==Specifications==
Alarm Schedules define when a [[Sensaphone.net API/contact|Contact]], or [[Sensaphone.net API/contactgroup|Contact Group]] will be notified of an alarm; immediately or with a predefined delay. Delays are user inputted integer values defining the number of minutes to wait after an alarm has been triggered to send a notification to a Contact, Contact Group, and/or Destination. Once an alarm is acknowledged it will not continue notifying subsequent delay tiers.

The schedule resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | alarmschedule | Object | The schedule object. | '''✓''' | '''✓''' | '''✓''' | '''n/a'''
}}{{TableRowN| alarmschedule | schedule_id | Integer | ID of the schedule. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| alarmschedule | timeranges | Array of Objects | The mapping of [[Sensaphone.net_API/timerange|time ranges]] to [[Sensaphone.net_API/calllist|call lists]] | '''✓''' | '''✓''' | '''✓''' | ''' '''
}}{{TableRowN| timeranges | range_id | Integer | The ID of the time range. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| timeranges | list_id | Integer | The ID of the call list. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| alarmschedule | calllist | Array of Objects | The schedule's [[Sensaphone.net_API/calllist|call lists]] | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| alarmschedule | timerange | Array of Objects | The schedule's [[Sensaphone.net_API/timerange|time ranges]] | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableEnd}}

===GET===

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN| ''<parent>'' | alarmschedule | Object | The schedule object.
}}{{TableRowN| alarmschedule | schedule_id | Integer | ID of the schedule.
}}{{TableRowN| alarmschedule | ''CHILD PROPERTY'' | '' '' | Alarm Schedule child properties to be edited*
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status''' | '''Type''' | '''Description'''
}}{{TableRowN| ''<parent>'' | alarmschedule | Optional | Object | The schedule object.
}}{{TableRowN| alarmschedule | schedule_id | Required | Integer | ID of the schedule.
}}{{TableRowN| alarmschedule | timeranges | Optional | Array of Objects | The mapping of [[Sensaphone.net_API/timerange|time ranges]] to [[Sensaphone.net_API/calllist|call lists]]
}}{{TableRowN| timeranges | range_id | Optional | Integer | The ID of the time range.
}}{{TableRowN| timeranges | list_id | Optional | Integer | The ID of the call list.
}}{{TableRowN| alarmschedule | calllist | Optional | Array of Objects | The schedule's [[Sensaphone.net_API/calllist|call lists]]
}}{{TableRowN| alarmschedule | timerange | Optional | Array of Objects | The schedule's [[Sensaphone.net_API/timerange|time ranges]]
}}{{TableEnd}}

====Example JSON====

===POST===
'''URI Mode Request URI's:'''
*Create a new device schedule.
'''POST''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/device_schedule

*Create a new zone alarm schedule.
'''POST''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone/{ZONE_ID}/alarm_zone/alarmschedule

'''JSON Mode Request URI:'''
'''POST''' https://rest.sensaphone.net/api/v1/device/device_schedule

'''JSON Mode Request Properties'''
''Create new alarm schedule''

This will create an alarm schedule with an empty call list and the default time range. An empty schedule must exist before its contents can be modified.

{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN| ''<parent>'' | alarmschedule | Object | The schedule object.
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property'''|'''Status''' | '''Type''' | '''Description'''
}}{{TableRowN| ''<parent>'' | alarmschedule | Optional | Object | The schedule object.
}}{{TableRowN| alarmschedule | schedule_id | Required | Integer | ID of the schedule.
}}{{TableRowN| alarmschedule | timeranges | Optional | Array of Objects | The mapping of [[Sensaphone.net_API/timerange|time ranges]] to [[Sensaphone.net_API/calllist|call lists]]
}}{{TableRowN| timeranges | range_id | Optional | Integer | The ID of the time range.
}}{{TableRowN| timeranges | list_id | Optional | Integer | The ID of the call list.
}}{{TableRowN| alarmschedule | calllist | Optional | Array of Objects | The schedule's [[Sensaphone.net_API/calllist|call lists]]
}}{{TableRowN| alarmschedule | timerange | Optional | Array of Objects | The schedule's [[Sensaphone.net_API/timerange|time ranges]]
}}{{TableEnd}}

===DELETE===
'''URI Mode Request URI's:'''
*Delete the device schedule from a device (thus enabling the default schedule).
'''DELETE''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/device_schedule/{SCHEDULE_ID}

*Delete a new zone alarm schedule.
'''POST''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone/{ZONE_ID}/alarm_zone/alarmschedule/{SCHED_ID}

'''JSON Mode Request URI:'''
'''POST''' https://rest.sensaphone.net/api/v1/device/device_schedule

'''JSON Mode Request Properties'''
:''Delete an existing alarm schedule''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN| ''<parent>'' | alarmschedule | Object | The schedule object.
}}{{TableRowN| alarmschedule | schedule_id | Integer | ID of the schedule.
}}{{TableEnd}}

Sensaphone.net API/calllist

2015-04-29T19:20:06Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=
==Specifications==
A call list is a combination of [[Sensaphone.net API/contactgroup|contactgroups]], [[Sensaphone.net API/user|users]], [[Sensaphone.net API/contact|contacts]] within one or more tiers (or, time waits after alarm delivery initiates). They are always contained in one or more [[Sensaphone.net API/alarmschedule|alarm schedules]]. Named call lists can act as templates to be added to various call lists. An unnamed call list is considered bound to the specific alarm schedule that contains it. If a named call list is used in multiple alarm schedules, than any modification to that call list take effect in every alarm schedule that uses it.

Call Lists give users a quick and easy way to add recurring Alarm Schedules to their devices. If the same Alarm Schedule is desired to be used recurrently, Call Lists provides a means to name and save a template to be used for other devices. This will allow a user to quickly add a Call List template to the Alarm Schedule instead of adding the same Contacts, Destinations, and/or Contact Groups for every device. The structure of a Call Lists is similar to that of an Alarm Schedule with the exception that you can name and save a Call List to be used again at a later time.

The call list resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | calllist | Array of Objects | The call list object | '''✓''' | '''✓''' | '''✓''' | '''n/a'''
}}{{TableRowN| calllist | list_id | Integer | ID of the call list. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| calllist | name | String | The name of the call list, or "" | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| calllist | tiers | Array | The tiers contained in this call list. | ''' ''' | '''✓''' | '''✓''' | ''' '''
}}{{TableRowN| tiers | tier_id | Integer | The tier number (in minutes) | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| tiers | seqential | Boolean | 'true' if the actions in the tier are processed sequentially. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| tiers | actions | Array of Objects | The actions in the call list | '''✓''' | '''✓''' | '''✓''' | '''n/a'''
}}{{TableRowN| actions | action_id | Integer | The ID of the action | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| actions | order | Integer | The order of delivery if sequential delivery is enabled. Lower numbers go first. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| actions | type | String | One of "user", "contact", or "group". | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| actions | user | Object | The ID of the user. 'null' for none. | '''✓''' | '''✓''' | '''✓''' | ''' '''
}}{{TableRowN| actions | contact | Object | The ID of the contact. 'null' for none. | '''✓''' | '''✓''' | '''✓''' | ''' '''
}}{{TableRowN| actions | group | Object | The ID of the group. 'null' for none. | '''✓''' | '''✓''' | '''✓''' | ''' '''
}}{{TableRowN| calllist | new_timeranges | Array | A special CREATE only property for call_lists under an alarm schedule | '''✓''' | ''' ''' | ''' ''' | ''' '''
}}{{TableEnd}}

===GET===
'''URI Mode Request URI's:'''
*Retrieve all the named call lists (those that are templates).
'''GET''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/calllist/
*Retrieve the list of tiers in a specific call list.
'''GET''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/calllist/{LIST_ID}/tiers

'''JSON Mode Request URI:'''
'''POST''' https://rest.sesnaphone.net/api/v1/calllist/

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | calllist | Array of Objects | The call list object.
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | calllist | Required | Array of Objects | The parent object.
}}{{TableRowN| calllist | list_id | Optional | Integer | ID of call list
}}{{TableRowN| calllist | name | Optional | String | The name of the call list, or ""
}}{{TableRowN| calllist | tiers | Optional | Array | The tiers contained in this call list.
}}{{TableRowN| tiers | tier_id | Optional | Integer | The tier number (in minutes)
}}{{TableRowN| tiers | seqential | Optional | Boolean | 'true' if the actions in the tier are processed sequentially.
}}{{TableRowN| tiers | actions | Optional | Array of Objects | The actions in the call list
}}{{TableRowN| actions | action_id | Optional | Integer | The ID of the action
}}{{TableRowN| actions | order | Optional | Integer | The order of delivery if sequential delivery is enabled. Lower numbers go first.
}}{{TableRowN| actions | type | Optional | String | One of "user", "contact", or "group".
}}{{TableRowN| actions | user | Optional | Object | The ID of the user. 'null' for none.
}}{{TableRowN| actions | contact | Optional | Object | The ID of the contact. 'null' for none.
}}{{TableRowN| actions | group | Optional | Object | The ID of the group. 'null' for none.
}}{{TableEnd}}

====Example JSON====
Retrieve the information for a call list.

*'''Request JSON:'''
{
"acctid": 987654,
"session": "0123-4567-8901",
"request_type": "read",
"calllist": [
{ "list_id": 7767 }
]
}

*'''Response JSON:'''
{
"result":
{
"success": true,
"code: 0,
"message": "OK",
}
"response":
{
"calllist":[
{
"list_id": 7767,
"name": "Primary Team",
"tiers":[
{
"tier_id": 3645,
"sequential": false,
"actions":[
{
"action_id": 8222,
"order": 1,
"type": "user",
"user": 4541 ,
"contact": null,
"contactgroup": null,
},
{
"action_id": 8246,
"order": 2,
"type": "contact",
"user": null,
"contact": 6646,
"contactgroup": null,
}
]
}
]
}
]
}
}

===PUT===
Tiers and Actions can only be updated in Json Mode

'''URI Mode Request URI's:'''
*Change the name of the call list. Setting this to anything but the blank string will make the call list a template.
'''PUT''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/calllist/{LIST_ID}/name/{NAME}
*Change a tier in the call list to a new time offset.
'''PUT''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/calllist/{LIST_ID}/tiers/{TIER_ID}/tier_id/{NEW_TIER_ID}

'''JSON Mode Request URI:'''
'''POST''' https://rest.sesnaphone.net/api/v1/calllist/

* Move a tier to a different time
'''POST''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/device
{
"request_type" : "update",
"device": [
{
"default_schedule": {
"calllist": [
{
"list_id": 1234,
"tiers": [
{
"tier_id": 20,
"minutes" : 25
}
]
}
],
"schedule_id": 1324
},
"device_id": 1234
}
]
}

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "update"
}}{{TableRowN|   | calllist | Array of Objects | The call list object.
}}{{TableRowN| calllist | list_id | Integer | ID of call list
}}{{TableRowN| calllist | '''''CHILD PROPERTY''''' |   | Child properties to be edited*
}}{{TableEnd}}
<nowiki>*</nowiki> One or more '''calllist''' child properties listed below are required in addition to "list_id".

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | calllist | Required | Array of Objects | The parent object.
}}{{TableRowN| calllist | list_id | Optional | Integer | ID of call list
}}{{TableRowN| calllist | name | Optional | String | The name of the call list, or ""
}}{{TableRowN| calllist | tiers | Optional | Array | The tiers contained in this call list.
}}{{TableRowN| tiers | tier_id | Optional | Integer | The tier number (in minutes)
}}{{TableRowN| tiers | seqential | Optional | Boolean | 'true' if the actions in the tier are processed sequentially.
}}{{TableRowN| tiers | actions | Optional | Array of Objects | The actions in the call list
}}{{TableRowN| actions | action_id | Optional | Integer | The ID of the action
}}{{TableRowN| actions | order | Optional | Integer | The order of delivery if sequential delivery is enabled. Lower numbers go first.
}}{{TableRowN| actions | type | Optional | String | One of "user", "contact", or "group".
}}{{TableRowN| actions | user | Optional | Object | The ID of the user. 'null' for none.
}}{{TableRowN| actions | contact | Optional | Object | The ID of the contact. 'null' for none.
}}{{TableRowN| actions | group | Optional | Object | The ID of the group. 'null' for none.
}}{{TableEnd}}

===POST===
Actions can only be created in Json Mode
'''URI Mode Request URI's:'''
*Create a new call list. The name must be provided.
'''POST''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/calllist/name/{NAME}
*Create a new tier in the call list.
'''POST''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/calllist/{LIST_ID}/tiers/minutes/{TIER_ID}/

'''JSON Mode Request URI:'''
'''POST''' https://rest.sesnaphone.net/api/v1/calllist/

*Create an Action
'''POST''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/device/
{
"request_type" : "create",
"device": [
{
"default_schedule": {
"calllist": [
{
"list_id": 1234,
"tiers": [
{
"tier_id": 20,
"actions" : [ {
"user" : 12345
} ]
}
]
}
],
"schedule_id": 1234
},
"device_id": 1234
}
]
}

*Link a Call List to a set of TimeRanges under an Alarm Schedule
'''POST''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/device/
{
"request_type" : "create",
"device": [
{
"device_id": 1234,
"default_schedule": {
"schedule_id": 5678,
"calllist": [
{
"list_id": 90123,
"new_timeranges": [
{
"start": 32166000,
"end": 32191200,
"interval": 2
}
]
}
]
}
}
]
}

'''JSON Mode Request Properties'''
:''Create a new call list.''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | calllist | Array of Objects | The call list object.
}}{{TableRowN| calllist | name | String | The name of the call list, or ""
}}{{TableEnd}}

:''Create a new action.''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | calllist | Array of Objects | The call list object.
}}{{TableRowN| calllist | list_id | Integer | ID of call list
}}{{TableRowN| calllist | tiers | Array | The tiers contained in this call list.
}}{{TableRowN| tiers | tier_id | Integer | The tier number (in minutes)
}}{{TableRowN| tiers | actions | Array of Objects | The actions in the call list
}}{{TableRowN| actions | user | Object | The ID of the contact. 'null' for none.
}}{{TableEnd}}

===DELETE===
'''URI Mode Request URI's:'''
*Delete a call list. Only named call lists can be deleted.
'''DELETE''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/calllist/{LIST_ID}
*Delete a tier in the call list.
'''DELETE''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/calllist/{LIST_ID}/tiers/{TIER_ID}
*Delete a user action in the call list's tier.
'''DELETE''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/calllist/{LIST_ID}/tiers/{TIER_ID}/actions/{ACTION_ID}/user/{USER_ID}

'''JSON Mode Request URI:'''
'''POST''' https://rest.sesnaphone.net/api/v1/calllist/

'''JSON Mode Request Properties'''
:''Delete a call list.''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | calllist | Array of Objects | The call list object.
}}{{TableRowN| calllist | list_id | Integer | ID of call list
}}{{TableRowN| calllist | name | String | The name of the call list, or ""
}}{{TableEnd}}

:''Delete a tier.''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | calllist | Array of Objects | The call list object.
}}{{TableRowN| calllist | list_id | Integer | ID of call list
}}{{TableRowN| calllist | tiers | Array | The tiers contained in this call list.
}}{{TableRowN| tiers | tier_id | Integer | The tier number (in minutes)
}}{{TableRowN| tiers | actions | Array of Objects | The actions in the call list
}}{{TableRowN| actions | user | Object | The ID of the contact. 'null' for none.
}}{{TableEnd}}

:''Delete a user action.''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | calllist | Array of Objects | The call list object.
}}{{TableRowN| calllist | list_id | Integer | ID of call list
}}{{TableRowN| calllist | tiers | Array | The tiers contained in this call list.
}}{{TableRowN| tiers | tier_id | Integer | The tier number (in minutes)
}}{{TableRowN| tiers | actions | Array of Objects | The actions in the call list
}}{{TableRowN| actions | user | Object | The ID of the contact. 'null' for none.
}}{{TableEnd}}

Sensaphone.net API/zone

2015-04-29T19:16:25Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[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'''
{{TableStart|border_size=1
}}{{TableRowN|'''Property'''|'''Digital'''|'''Analog'''|'''Internal'''|'''External'''|'''Generic'''|'''Input'''|'''Output'''|'''IP Alarm'''|'''Alarmable'''|'''Table Ranged'''|'''Loggable'''|'''Alarm Low'''|'''Alarm High'''
}}{{TableRowN| wireless_zone|''' '''|''' '''|''' '''|'''✓'''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''
}}{{TableRowN| pulse_zone|'''✓'''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''
}}{{TableRowN| runtime_zone|'''✓'''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''
}}{{TableRowN| output_zone|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|'''✓'''|''' '''|''' '''|''' '''|''' '''|'''✓'''|''' '''
}}{{TableRowN| alarm_zone|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|'''✓'''|''' '''|''' '''|'''✓'''|''' '''
}}{{TableRowN| table_zone|''' '''|'''✓'''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|'''✓'''|''' '''|''' '''|''' '''
}}{{TableRowN| loggable_zone|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|'''✓'''|''' '''|''' '''
}}{{TableRowN| alarm_low|''' '''|'''✓'''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|'''✓'''|''' '''|''' '''|'''✓'''|''' '''
}}{{TableRowN| alarm_high|''' '''|'''✓'''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|'''✓'''|''' '''|''' '''|''' '''|'''✓'''
}}{{TableRowN| modbus_zone|''' '''|''' '''|''' '''|''' '''|'''✓'''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''|''' '''
}}{{TableEnd}}

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

'''Output Mode Type''' {{TableStart|border_size=1
}}{{TableRowN| '''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN| name | String | Name
}}{{TableRowN| action | String | Action
}}{{TableRowN| zone_list | Array of Objects | List of zones
}}{{TableRowN| type_list | Array of Objects | List of Zone type
}}{{TableRowN| trigger | String | Trigger
}}{{TableRowN| compare_on | String | Compare On
}}{{TableRowN| compare_off | String | Compare Off
}}{{TableRowN| limit_on | Float | Limit On
}}{{TableRowN| limit_off | Float | Limit Off
}}{{TableRowN| zone_on | String | Zone On
}}{{TableRowN| zone_off | String | Zone Off
}}{{TableEnd}}

=== 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''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone

*Retrieve all information for a single zone.

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

*Retrieve the a specific zone's type.

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

'''JSON Mode Request URI:'''

'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device/zone

'''JSON Mode Request Properties''' {{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | device | Array of Objects | The parent device of the "zone" resource. See [[Sensaphone.net_API/device|device]].
}}{{TableRowN| device | zone | Array of Objects | The zone object
}}{{TableEnd}}

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

==== 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''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone/{ZONE_ID}/name/{ZONE_NAME}
*Edit a Zone's recognition time value
'''PUT''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone/{ZONE_ID}/alarm_zone/rec_time/{REC_TIME}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device/zone

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | device | Array of Objects | The parent device of the "zone" resource. See [[Sensaphone.net_API/device|device]].
}}{{TableRowN| device | zone | Array of Objects | The zone object.
}}{{TableRowN| zone | zone_id | Integer | ID of the zone.
}}{{TableRowN| zone | '''''CHILD PROPERTY''''' |   | Zone's child properties to be edited*
}}{{TableEnd}}
<nowiki>*</nowiki> One or more '''zone''' child properties listed below are required in addition to "zone_id".

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

===POST===
'''URI Mode Request URI's:'''
*Acknowledge All Zone Alarms
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/zone/{ZONE_ID}/alarm_zone/acknowledge_all_alarms/{true}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device/zone

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | device | Array of Objects | The parent device of the "zone" resource. See [[Sensaphone.net_API/device|device]].
}}{{TableRowN| device | zone | Array of Objects | The zone object.
}}{{TableRowN| zone | zone_id | Integer | ID of the zone.
}}{{TableRowN| zone | alarm_zone | Object | Sub-object containing data for alarmable zones
}}{{TableRowN| alarm_zone | acknowledge_alarms | Array of Zone State | A write-only property to acknowledge specific alarms
}}{{TableRowN| alarm_zone | acknowledge_all_alarms | Boolean | A write-only property to acknowledge all alarms for a zone
}}{{TableEnd}}
<nowiki>*</nowiki> "acknowledge_all_alarms" supersedes "acknowledge_alarms", if it is present in the request json other properties will be ignored

'''JSON Mode Result Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | device | Required | Array of Objects | The parent device object.
}}{{TableRowN| device | zone | Required | Array of Objects | The zone object.
}}{{TableRowN| zone | zone_id | Required | Integer | ID of the zone.
}}{{TableRowN| zone | alarm_zone | Required | Object | Sub-object containing data for alarmable zones. 'null' if unsupported.
}}{{TableRowN| alarm_zone | acknowledge_alarms | Optional | Array of Zone State | A write-only property to acknowledge specific alarms
}}{{TableRowN| alarm_zone | acknowledge_all_alarms | Optional | Boolean | A write-only property to acknowledge all alarms for a zone
}}{{TableEnd}}

=== 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/coordinates

2015-04-29T19:14:49Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=
==Specifications==
The '''coordinates''' object holds latitude and longitude coordinates. It is not an individual (top-level) API resource, but is instead used in conjunction with other resources (e.g. [[Sensaphone.net API/device|devices]]).

The coordinates resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | coordinates | Object | The coordinates object. | ''' ''' | ''' ''' | '''✓''' | '''n/a'''
}}{{TableRowN| coordinates | coordinates_id | Integer | ID of the address. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| coordinates | lng | Floating Point | Longitude | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| coordinates | lat | Floating Point | Latitude | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| coordinates | cached | Boolean | Are coordinates from geocoding cache | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableEnd}}

===GET===
'''URI Mode Request URI's:'''
*Retrieve all the coordinate data for a particular device.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/coordinates

*Retrieve the latitude coordinate for a particular device's address.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/coordinates/lat

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device/coordinates

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Properties''' | '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "address" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | coordinates | Array of Objects | The coordinates object
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | coordinates | Required | Array of Objects | Address data
}}{{TableRowN| coordinates | coordinates_id | Required | Integer | ID of the address.
}}{{TableRowN| coordinates | lng | Optional | Floating Point | Longitude
}}{{TableRowN| coordinates | lat | Optional | Floating Point | Latitude
}}{{TableRowN| coordinates | cached | Optional | Boolean | Are coordinates from geocoding cache
}}{{TableEnd}}

====Example JSON====
Receive coordinates for a device.

*'''Request JSON:'''
{
"acctid": 987654,
"sessionid": "0123-4567-8901",
"request_type": "read",
"device":[
{
"device_id": 1234,
"coordinates": null
}
}

*'''Response JSON'''
{
"result":
{
"success": true,
"code": 0,
"message": "OK"
},
"response":
{
"device":[
{
"device_id": 1234,
"coordinates":[
{
"coordinates_id": 28487,
"lat": 39.868809,
"lng": -75.674508
}
]
}
]
}
}

===PUT===
'''URI Mode Request URI's:'''
*Edit the coordinates's latitude coordinate.
'''PUT''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SEESIONID}/device/{DEVICE_ID}/coordinates/lat/{LATITUDE}

'''JSON Mode Request URI:'''
'''POST''' https://rest.sensaphone.net/api/v1/device/coordinates

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Properties''' | '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "address" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | coordinates | Array of Objects | The coordinates object
}}{{TableRowN| coordinates | '''''CHILD PROPERTY''''' |   | Coordinate's child properties to be edited*
}}{{TableEnd}}
<nowiki>*</nowiki>One or more '''coordinates''' child properties listed below is required (other than "coordinates_id").

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | coordinates | Required | Array of Objects | Address data
}}{{TableRowN| coordinates | coordinates_id | Required | Integer | ID of the address.
}}{{TableRowN| coordinates | lng | Optional | Floating Point | Longitude
}}{{TableRowN| coordinates | lat | Optional | Floating Point | Latitude
}}{{TableEnd}}

Sensaphone.net API/address

2015-04-29T19:13:17Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=
==Specifications==
The Address object holds street address information. It is not an individual (top-level) API resource, but is instead used in conjunction with other resources in a number of contexts including [[Sensaphone.net API/device|devices]] and [[Sensaphone.net API/user|users]]. It may be used as its own entity (e.g. users) or as part of a location (e.g. devices). The "address" resource cannot be created or deleted. Because the address ID is fixed and predetermined, it is not required to access the resource, although it may be optionally specified.

The address resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | address | Object | The address object. | ''' ''' | ''' ''' | '''✓''' | '''n/a'''
}}{{TableRowN| address | address_id | Integer | ID of the address. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| address | address_line_1 | String | First line of street address | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| address | address_line_2 | String | Second line of street address | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| address | city | String | City | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| address | state | String | State | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| address | zip | String | Zip Code | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| address | country | String | Country | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableEnd}}

===GET===
'''URI Mode Request URI's:'''
*Retrieve all the address data for a particular device.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/address

*Retrieve the city for a particular device's address.
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/address/city

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device/address

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Properties''' | '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "address" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | address | Array of Objects | The address object
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | address | Required | Array of Objects | Address data
}}{{TableRowN| address | address_id | Required | Integer | ID of the address.
}}{{TableRowN| address | address_line_1 | Optional | String | First line of street address
}}{{TableRowN| address | address_line_2 | Optional | String | Second line of street address
}}{{TableRowN| address | city | Optional | String | City
}}{{TableRowN| address | state | Optional | String | State
}}{{TableRowN| address | zip | Optional | String | Zip code
}}{{TableRowN| address | country | Optional | String | Country of address
}}{{TableEnd}}

====Example JSON====
Receive city value of an Address

*'''Request JSON:'''
{
"acctid": 987654,
"sessionid": "0123-4567-8901",
"request_type": "read",
"device":[
{
"device_id": 1234,
"address": [
{
"city": null
}
]
}
}

*'''Response JSON'''
{
"result":
{
"success": true,
"code": 0,
"message": "OK"
},
"response":
{
"device":[
{
"device_id": 1234,
"address": [
{
"address_id": 13553
"city": "Kennett Square"
}
]
}
]
}
}

===PUT===
'''URI Mode Request URI's:'''
*Edit the address's '''state'''
'''PUT''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SEESIONID}/device/{DEVICE_ID}/address/state/{STATE}

'''JSON Mode Request URI:'''
'''POST''' https://rest.sensaphone.net/api/v1/device

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Properties''' | '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "update"
}}{{TableRowN|   | ''<parent object(s)>'' | Array of Objects | The parent(s) of the "address" resource, if any. See the [[Sensaphone.net_API#List|'''list''']].
}}{{TableRowN| ''<parent>'' | address | Array of Objects | The address object
}}{{TableRowN| address | '''''CHILD PROPERTY''''' |   | Address's child properties to be edited*
}}{{TableEnd}}
<nowiki>*</nowiki>One or more '''address''' child properties listed below is required (other than "address_id").

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | address | Required | Array of Objects | Address data
}}{{TableRowN| address | address_id | Required | Integer | ID of the address.
}}{{TableRowN| address | address_line_1 | Optional | String | First line of street address
}}{{TableRowN| address | address_line_2 | Optional | String | Second line of street address
}}{{TableRowN| address | city | Optional | String | City
}}{{TableRowN| address | state | Optional | String | State
}}{{TableRowN| address | zip | Optional | String | Zip code
}}{{TableRowN| address | country | Optional | String | Country of address
}}{{TableEnd}}

Sensaphone.net API/devicegroup

2015-04-29T19:12:01Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=
Sensaphone.net includes a feature to group individual devices together. The DeviceGroup API allows a user to view and edit grouping information.

==Specifications==

The device group resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' | '''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | devicegroup | Object | The devicegroup object. | '''✓''' | '''✓''' | '''✓''' | '''n/a'''
}}{{TableRowN| devicegroup | group_id | Integer | ID of the device group. | ''' ''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| devicegroup | name | String | The name of this group. | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| devicegroup | devices | Array of Objects | The list of devices in this group. | '''✓''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| devices | device_id | Integer | The device_id of a device that is a member of this group. | '''✓''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| devicegroup | groups | Array of Objects | The list of groups in this group. | '''✓''' | ''' ''' | '''✓''' | ''' '''
}}{{TableRowN| groups | group_id | Integer | The group_id of a group that is a member of this group. | '''✓''' | ''' ''' | '''✓''' | ''' '''
}}{{TableEnd}}

===GET===
'''URI Mode Request URI's:'''
*Receive all Device Group information
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/devicegroup

*Receive all Device Group names
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/devicegroup/name

*Receive all Device ID's in a Device Group
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/devicegroup/{GROUP_ID}/devices/device_id

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/devicegroup

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | devicegroup | Array of Objects | The devicegroup object.
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | devicegroup | Required | Array of Objects | The parent device object.
}}{{TableRowN| devicegroup | group_id | Optional | Integer | ID of Device Group
}}{{TableRowN| devicegroup | name | Optional | String | The name of this group.
}}{{TableRowN| devicegroup | devices | Optional | Array of Objects | The list of devices in this group.
}}{{TableRowN| devices | device_id | Optional | Integer | The device_id of a device that is a member of this group.
}}{{TableRowN| devicegroup | groups | Optional | Array of Objects | The list of groups in this group.
}}{{TableRowN| groups | group_id | Optional | Integer | The group_id of a group that is a member of this group.
}}{{TableEnd}}

====Example JSON====
Receive all Device Group information

*'''Request JSON:'''
{
"acctid": 987654,
"session": "0123-4567-8901",
"request_type": "read",
"devicegroup": null
}

*'''Response JSON:'''
{
"result":
{
"success": true,
"code: 0,
"message": "OK",
}
"response":
{
"devicegroup":[
{
"group_id": 6575,
"name": "South Barns",
"devices":
[
{ "device_id": 1234 },
{ "device_id": 1235 }
],
"groups":
[
{ "group_id": 8575 },
{ "group_id": 8404 }
]
}
]
}
}

===PUT===
The '''PUT''' request for the device group resource is used to edit the group:
*Change the name
*Add or remove devices (JSON mode only)
*Add or remove groups (JSON mode only)

'''URI Mode Request URI:'''
*Edit a Device Group '''name'''
'''PUT''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/devicegroup/{GROUP_ID}/name/{GROUP_NAME}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/devicegroup

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "update"
}}{{TableRowN|   | devicegroup | Array of Objects | The devicegroup object.
}}{{TableRowN| devicegroup | group_id | Integer | ID of the device group.
}}{{TableRowN| devicegroup | group_name | String | New name of a Device Group
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | devicegroup | Required | Array of Objects | The parent device object.
}}{{TableRowN| devicegroup | group_id | Optional | Integer | ID of Device
}}{{TableRowN| devicegroup | name | Optional | String | The name of this group.
}}{{TableRowN| devicegroup | devices | Optional | Array of Objects | The list of devices in this group.
}}{{TableRowN| devices | device_id | Optional | Integer | The device_id of a device that is a member of this group.
}}{{TableRowN| devicegroup | groups | Optional | Array of Objects | The list of groups in this group.
}}{{TableRowN| groups | group_id | Optional | Integer | The group_id of a group that is a member of this group.
}}{{TableEnd}}

===POST===
'''URI Mode Request URI's:'''
*Create a new empty Device Group (A '''group_name''' value is required when creating a new Device Group)
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/devicegroup/name/{GROUP_NAME}

*Add a device to a device group
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/devicegroup/{GROUP_ID}/devices/device_id/{DEVICE_ID}

*Add a group to a device group
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/devicegroup/{GROUP_ID}/groups/group_id/{GROUP_ID}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphon.net/api/v1/devicegroups

'''JSON Mode Request Properties'''
:''Create new device group''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | devicegroup | Array of Objects | The devicegroup object.
}}{{TableRowN| devicegroup | name | String | New name of a Device Group.
}}{{TableEnd}}

:''Add device and/or group''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | devicegroup | Array of Objects | The devicegroup object.
}}{{TableRowN| devicegroup | group_id | Integer | ID of Device
}}{{TableRowN| devicegroup | devices | Array of Objects | Used to add devices to the group.
}}{{TableRowN| devices | device_id | Integer | The device_id of a [[Sensaphone.net API/device|device]] to add to this group.
}}{{TableRowN| devicegroup | groups | Array of Object | Used to add groups to the group.
}}{{TableRowN| groups | group_id | Integer | The group_id of a group to add to this group.
}}{{TableEnd}}

'''JSON Mode Response Properties'''
:{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | devicegroup | Required | Array of Objects | The parent device object.
}}{{TableRowN| devicegroup | group_id | Optional | Integer | ID of Device
}}{{TableRowN| devicegroup | name | Optional | String | The name of this group.
}}{{TableRowN| devicegroup | devices | Optional | Array of Objects | The list of devices in this group.
}}{{TableRowN| devices | device_id | Optional | Integer | The device_id of a device that is a member of this group.
}}{{TableRowN| devicegroup | groups | Optional | Array of Objects | The list of groups in this group.
}}{{TableRowN| groups | group_id | Optional | Integer | The group_id of a group that is a member of this group.
}}{{TableEnd}}

===DELETE===
'''URI Mode Request URI's:'''
*Delete a device group
'''DELETE''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/devicegroup/{GROUP_ID}

*Delete a device from a device group
'''DELETE''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/devicegroup/{GROUP_ID}/devices/device_id/{DEVICE_ID}

*Delete a group from a device group
'''DELETE''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/devicegroup/{GROUP_ID}/groups/group_id/{GROUP_ID}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/devicegroup

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "delete"
}}{{TableRowN|   | devicegroup | Array of Objects | The devicegroup object.
}}{{TableRowN| devicegroup | group_id | Integer | ID of the device group.
}}{{TableRowN| devicegroup | devices | Array of Objects | Used to remove devices from the group. (Optional)
}}{{TableRowN| devices | device_id | Integer | The device_id of a device that is a member of this group.
}}{{TableRowN| devicegroup | groups | Array of Object | Used to remove groups from the group. (Optional)
}}{{TableRowN| groups | group_id | Integer | The group_id of a group that is a member of this group.
}}{{TableEnd}}

Sensaphone.net API/device

2015-04-29T19:11:01Z

Mwood: /* Specifications */ Change 'clone' description wording

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

'''Zone Meta Type'''
{{TableStart|border_size=1
}}{{TableRowN| '''Property''' |'''Type''' | '''Description'''
}}{{TableRowN| zone_id | Integer | The Zone ID
}}{{TableRowN| is_enabled | Integer | Is the zone enabled
}}{{TableRowN| hide_if_disabled | Boolean | Hide the zone if disabled
}}{{TableRowN| add_name | String | The add name
}}{{TableEnd}}

===GET===
'''URI Mode Request URI's:'''
*Receive all Device data for all Devices in a user's account
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device

*Receive all Device data for a specific Device
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}

*Receive the alarm status of a Device
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/status

*Receive the changlog from a particular firmware version
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/firmware_changelog/{FIRMWARE_ID}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | device | Array of Objects | The device object.
}}{{TableRowN| device | firmware_changelog | Object | The changelog is only returned if specified explicitly in the request
}}{{TableRowN| firmware_changelog | firmware_id | Integer | The ID of the firmware to get the changelog from
}}{{TableEnd}}

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

=====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''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/description/{DESCRIPTION}

*Edit the '''name''' of a Device
'''PUT''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/name/{DEVICE_NAME}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "update"
}}{{TableRowN|   | device | Array of Objects | The device object.
}}{{TableRowN| device | device_id | Integer | ID of the device.
}}{{TableRowN| device | '''CHILD PROPERTY''' |   | Device's child properties to be edited*
}}{{TableEnd}}
<nowiki>*</nowiki>One or more '''device''' child properties below are required in addition to "device_id".

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

===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''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/id/{DEVICEID}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | device | Array of Objects | The device object.
}}{{TableRowN| device | id | String | Unique identifier located on the Device (Serial number, etc.)
}}{{TableEnd}}

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

'''Acknowledging Alarms'''

'''URI Mode Request URI:'''
*Acknowledge All Alarms
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/acknowledge_all_alarms/{true}

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "create"
}}{{TableRowN|   | device | Array of Objects | The device object.
}}{{TableRowN| device | device_id | Integer | ID of Device
}}{{TableRowN| device | ack_offline_alarm | Boolean | A write-only property that will acknowledge a device offline alarm
}}{{TableRowN| 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
}}{{TableEnd}}
<nowiki>*</nowiki> "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''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/device

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "delete"
}}{{TableRowN|   | device | Array of Objects | The device object.
}}{{TableRowN| device | device_id | Integer | ID of the device.
}}{{TableEnd}}

Sensaphone.net API/account

2015-04-29T19:10:02Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=
==Specifications==
The account resource

The account resource has the following properties:
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Property''' | '''Type''' | '''Description''' | '''Create''' | '''Delete''' | '''Read''' | '''Update'''
}}{{TableRowN| ''<parent>'' | account | Object | The account object. | ''' ''' | ''' ''' | '''✓''' | '''n/a'''
}}{{TableRowN| account | name | String | The name of the account | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| account | timezone | String | The timezone which the account is in | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableRowN| account | feature | Array of Object | The feature linked to the account (See [[Sensaphone.net API/feature]]) | ''' ''' | ''' ''' | '''✓''' | '''✓'''
}}{{TableEnd}}

===GET===
'''URI Mode Request URI's:'''
*Retrieve all the account data
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/account

*Retrieve the account name
'''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/account/name

'''JSON Mode Request URI:'''
'''POST''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/account

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Properties''' | '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN| ''<parent>'' | account | Array of Objects | The accounts object
}}{{TableEnd}}

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | account | Required | Array of Objects | Account Data
}}{{TableRowN| account | name | Optional | String | The name of the account
}}{{TableRowN| account | timezone | Optional | String | The timezone which the account is in
}}{{TableRowN| account | feature | Optional | Array of Objects | The feature linked to the account (See [[Sensaphone.net API/feature]])
}}{{TableEnd}}

====Example JSON====
Receive the account name and timezone

*'''Request JSON:'''
{
"acctid": 987654,
"sessionid": "0123-4567-8901",
"request_type": "read",
"account": [
{
"name" : null,
"timezone" : null
}
]
}

*'''Response JSON'''
{
"result":
{
"success": true,
"code": 0,
"message": "OK"
},
"response":
{
"account": [
{
"name":"John's Account",
"timezone":"Central Time"
}]
}
}

===PUT===
'''URI Mode Request URI's:'''
*Edit the account's name.
'''PUT''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SEESIONID}/account/{NAME}

'''JSON Mode Request URI:'''
'''POST''' https://rest.sensaphone.net/api/v1/account

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Properties''' | '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session Token
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN| ''<parent>'' | account | Array of Objects | The accounts object
}}{{TableRowN| account | '''''CHILD PROPERTY''''' |   | Account's child properties to be edited*
}}{{TableEnd}}
<nowiki>*</nowiki>One or more '''account''' child properties listed below is required

'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Properties''' | '''Child Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN|   | ''<parent object(s)>'' | Optional | Array of Objects | The parent(s) specified in the request.
}}{{TableRowN| ''<parent>'' | account | Required | Array of Objects | Account Data
}}{{TableRowN| account | name | Optional | String | The name of the account
}}{{TableRowN| account | timezone | Optional | String | The timezone which the account is in
}}{{TableEnd}}

Sensaphone.net API/history

2015-04-29T18:18:48Z

Mwood: /* Event Log */

=[[Sensaphone.net API]]=

==Access==
The History API allows access to the Audit Log, the Data Log, and the Event Log

==Specifications==
The URI Mode for the History API is unique because it allows filtering options to be specified in pairs and can be added in any order. Also, the array values are expressed as a common-separated list.
/history/audit_log/var_ids/{1234,9876}/changes/{create}

==Timestamps==
The history APIs such as the Data Log use Sensaphone encoded timestamps. This allows the timestamps to be independent of the time zone of the client request, and return results adjusted to the time zone of the device, account, etc. Seconds, minutes, hours, days, and months are 0-indexed, in other words the range of month values is [0,11]. The year value is 2000-based and limited to 100 years.

In order to create a Sensaphone timestamp given the year, month, day, hours, minutes, and seconds, convert each parameter to its equivalent value in seconds. For the example, in pseudo-code, a factory method would look as following:

getSensaphoneTimestamp( year, month, day, hours, minutes, seconds ) {
return ((seconds % 60)) +
((minutes * 60) % 3600) +
((hours * 3600) % 86400) +
((day * 86400) % 2678400) +
((month * 2678400) % 32140800) +
((year % 100 * 32140800));
}

==Audit Log==

'''Audit Log Filter Options'''
{{TableStart|border_size=1
}}{{TableRowN| '''Property''' |'''Status''' | '''Type''' | '''Description'''
}}{{TableRowN| var_ids | Optional | Array of Integer | list of variable ids
}}{{TableRowN| user_ids | Optional | Array of Integer | list of user ids
}}{{TableRowN| changes | Optional | Array of String | list of change types ("create","delete","update")
}}{{TableRowN| start | Optional | Integer | the start time (Sensaphone timestamp)
}}{{TableRowN| end | Optional | Integer | the end time (Sensaphone timestamp)
}}{{TableRowN| begin_offset | Optional | Integer | page through results by incrementing this number by multiples of 'record_offset'
}}{{TableRowN| record_offset | Optional | Integer | number of records returned per query; or 'page' size
}}{{TableEnd}}

===GET===

'''Audit Log Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''| '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session ID
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | history | Object | The History object
}}{{TableRowN| history | audit_log | Object | Audit Log Filter Options
}}{{TableEnd}}

'''Audit Log Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''| '''Type''' | '''Description'''
}}{{TableRowN|   | history | Object | The history object
}}{{TableRowN| history | audit_log | Array of Objects | The returned log
}}{{TableRowN| audit_log | change | String | The change that occurred
}}{{TableRowN| audit_log | who | String | Who changed it
}}{{TableRowN| audit_log | what | String | What changed
}}{{TableRowN| audit_log | when | String | When it changed
}}{{TableRowN| audit_log | epoch | Integer | The epoch time
}}{{TableRowN| history | audit_log_filter | Object | Audit Log Filter Options (Only returned in V2)
}}{{TableEnd}}

*Receive all changes for a variable:
*'''URI Mode:'''
'''GET''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/audit_log/var_ids/{1234}

*'''JSON Mode:'''
'''POST''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/audit_log/

{
"request_type": "read",
"history":
{
"audit_log": {
"var_ids" : [1234]
}
}
}

==Data Log==

'''Data Log Filter Options'''
{{TableStart|border_size=1
}}{{TableRowN| '''Property''' |'''Status''' | '''Type''' | '''Description'''
}}{{TableRowN| log_points | Optional | Array of Integer | list of variable ids
}}{{TableRowN| status | Optional | Array of String | list of AlarmStatus ("normal", "dependency", "alarm")
}}{{TableRowN| start | Optional | Integer | the start time (Sensaphone timestamp)
}}{{TableRowN| end | Optional | Integer | the end time (Sensaphone timestamp)
}}{{TableRowN| begin_offset | Optional | Integer | page through results by incrementing this number by multiples of 'record_offset'
}}{{TableRowN| record_offset | Optional | Integer | number of records returned per query; or 'page' size
}}{{TableEnd}}

===GET===

'''Data Log Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property''' | '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session ID
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | history | Object | The History object
}}{{TableRowN| history | data_log | Object | Data Log Filter Options
}}{{TableEnd}}

'''Data Log Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''| '''Type''' | '''Description'''
}}{{TableRowN|   | history | Object | The history object
}}{{TableRowN| history | data_log | Array of Objects | The returned log
}}{{TableRowN| data_log | record_id | String | The id of the record
}}{{TableRowN| data_log | value | String | The value of the variable
}}{{TableRowN| data_log | variable | String | The variable id
}}{{TableRowN| data_log | is_alarm | String | Is an alarm
}}{{TableRowN| data_log | epoch | Integer | The epoch time
}}{{TableRowN| history | data_log_filter | Object | Audit Log Filter Options (Only returned in V2)
}}{{TableEnd}}

*Receive the last 50 logged datas for a log point
*'''URI Mode:'''
'''GET''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log/log_points/{1234}/begin_offset/{0}/record_offset/{50}

*'''JSON Mode:'''
'''POST''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log

{
"request_type": "read",
"history":
{
"data_log": {
"log_points" : [1234],
"begin_offset" : 0,
"record_offset" : 50
}
}
}

==Data Log Points==
Poll the Data Log Points to get the possible logable points to use for the Data Log

===GET===

'''Data Log Points Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''| '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session ID
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | history | Object | The History object
}}{{TableRowN| history | data_log_points | Object |
}}{{TableRowN| data_log_points | resource_type | String | the name of the resource, e.g. "device"
}}{{TableRowN| data_log_points | (id_name) | Integer | The ID of the resource, e.g. "device_id"
}}{{TableEnd}}

'''Data Log Points Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''| '''Type''' | '''Description'''
}}{{TableRowN|   | history | Object | The history object
}}{{TableRowN| history | data_log_points | Object | The returned log
}}{{TableRowN| data_log_points | resource_type | String | the name of the resource, e.g. "device"
}}{{TableRowN| data_log_points | (id_name) | Integer | The ID of the resource, e.g. "device_id"
}}{{TableRowN| data_log_points | log_points | Array of Objects | The logable points
}}{{TableRowN| log_points | category | String | The type of logable point
}}{{TableRowN| log_points | (id_name) | Integer | The ID of the resource, e.g. "zone_id"
}}{{TableRowN| log_points | log_point | Integer | The logable point ID
}}{{TableEnd}}

*Receive all data logable points for a device:
*'''URI Mode:'''
'''GET''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log_points/resource_type/{device}/device_id/{1234}

*'''JSON Mode:'''
'''POST''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log_points

{
"request_type": "read",
"history":
{
"data_log_points": {
"resource_type" : "device",
"device_id" : 1234
}
}
}

==Event Log==

'''Event Log Filter Options'''
{{TableStart|border_size=1
}}{{TableRowN| '''Property''' |'''Status''' | '''Type''' | '''Description'''
}}{{TableRowN| contact_ids | Optional | Array of Integer | list of contact ids
}}{{TableRowN| device_ids | Optional | Array of Integer | list of device ids
}}{{TableRowN| zone_ids | Optional | Array of Integer | list of zone ids
}}{{TableRowN| user_ids | Optional | Array of Integer | list of user ids
}}{{TableRowN| event_types | Optional | Array of String | list of event types
}}{{TableRowN| start | Optional | Integer | the start time (Sensaphone timestamp)
}}{{TableRowN| end | Optional | Integer | the end time (Sensaphone timestamp)
}}{{TableRowN| begin_offset | Optional | Integer | page through results by incrementing this number by multiples of 'record_offset'
}}{{TableRowN| record_offset | Optional | Integer | number of records returned per query; or 'page' size
}}{{TableEnd}}

===GET===

'''Event Log Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''| '''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session ID
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | history | Object | The History object
}}{{TableRowN| history | event_log | Object | Event Log Filter Options
}}{{TableEnd}}

'''Event Log Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''| '''Type''' | '''Description'''
}}{{TableRowN|   | history | Object | The history object
}}{{TableRowN| history | event_log | Array of Objects | The returned log
}}{{TableRowN| event_log | event | String | Which event
}}{{TableRowN| event_log | when | String | When it changed
}}{{TableRowN| event_log | epoch | Integer | The epoch time
}}{{TableRowN| event_log | type | String | The type
}}{{TableRowN| event_log | source | Object | The sources of the event
}}{{TableRowN| source | <source_name> | String | A source
}}{{TableRowN| history | event_log_filter | Object | Event Log Filter Options (Only returned in V2)
}}{{TableEnd}}

*Receive last 50 "Alarms Events" for a device:
*'''URI Mode:'''
'''GET''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/event_log/device_ids/{1234}/event_types/{alarm}/begin_offset/{0}/record_offset/{50}

*'''JSON Mode:'''
'''POST''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/event_log

{
"request_type": "read",
"history":
{
"event_log": {
"event_types" : ["alarm"],
"device_ids" : [1234],
"begin_offset" : 0,
"record_offset" : 50
}
}
}

Sensaphone.net API/dashboard

2015-04-29T18:17:55Z

Derek: /* Example */

=[[Sensaphone.net API]]=

Receive data to populate Dashboard. The Dashboard is a page that gives the user a quick view of Device and alarm statuses. It is a read only resource.

==Example Call==

http://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/dashboard

==Example Requests==
===GET===
'''URI Mode Request URI's:'''
*Receive all Dashboard information
'''GET''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/dashboard

*Receive for the number of Devices online
'''GET''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/dashboard/devices_online

*Receive the names of all Devices powered on and online
'''GET''' https://rest.sensaphone.net/api/v1/{ACCTID}/{UUID}/dashboard/device/name
'''JSON Mode Request URI:'''
'''POST''' https://rest.sensaphone.net/api/v1/dashboard

'''JSON Mode Request Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property'''|'''Child Property''' |'''Type''' | '''Description'''
}}{{TableRowN|   | acctid | Integer | Account ID
}}{{TableRowN|   | session | String | Session ID
}}{{TableRowN|   | request_type | String | "read"
}}{{TableRowN|   | dashboard | Object | The dashboard object.
}}{{TableEnd}}
 
'''JSON Mode Response Properties'''
{{TableStart|border_size=1
}}{{TableRowN| '''Parent Property''' |'''Child Property'''|'''Status'''| '''Type''' | '''Description'''
}}{{TableRowN|   | dashboard | Required | Object | The dashboard object.
}}{{TableRowN| dashboard | online_count | Optional | Integer | Number of Devices turned on and online
}}{{TableRowN| dashboard | offline_count | Optional | Integer | Number of Devices offline
}}{{TableRowN| dashboard | alarm_count | Optional | Integer | Number of acknowledged alarms
}}{{TableRowN| dashboard | unack_count | Optional | Integer | Number of unacknowledged alarms
}}{{TableRowN| dashboard | total_alarm_count | Optional | Integer | Number of alarms
}}{{TableRowN| dashboard | device | Optional | Array | Array of Devices
}}{{TableRowN| device | device_id | Optional | Integer | ID of Device
}}{{TableRowN| device | id | Optional | Integer | Unique identifier located on the Device (Serial number, etc.)
}}{{TableRowN| device | name | Optional | String | Name of Device
}}{{TableRowN| device | location | Optional | Object | Contains location information for the device.
}}{{TableRowN| location | address | Optional | Object | Address information for Device (See [[Sensaphone.net API/address]])
}}{{TableRowN| location | coordinates | Optional | Object | GPS Coordinates information for Device (See [[Sensaphone.net API/coordinates]])
}}{{TableRowN| device | status | Optional | String | Alarm status of Device("OK" or "Alarm")
}}{{TableRowN| device | is_offline_unack | Optional | Boolean | Whether or not an '''unacknowledged''' offline alarm exists.
}}{{TableRowN| device | is_online | Optional | Boolean | Whether or not the device is currently online.
}}{{TableRowN| device | battery_status | Optional | String | A device's battery status
}}{{TableRowN| device | power_status | Optional | String | A device's power status
}}{{TableRowN| device | battery_value | Optional | String | A device's battery value
}}{{TableRowN| device | power_value | Optional | String | A device's power value
}}{{TableRowN| device | connection_status | Optional | String | A device's connection status
}}{{TableRowN| device | zone | Optional | Array of Objects | Device Zone data (See [[Sensaphone.net API/zone|Sensaphone.net API/zone]]) *Only returns zones with an alarm
}}{{TableRowN| zone | canonical_name | Optional | String | Canonical name of the zone.
}}{{TableRowN| zone | value | Optional | String | The data value for the zone.
}}{{TableRowN| zone | type | Optional | String | The zone type.
}}{{TableRowN| zone | alarm_zone | Optional | Object | Sub-object containing data for alarmable zones. 'null' if unsupported.
}}{{TableRowN| alarm_zone | alarm_status | Optional | Array of ZoneState | The processed status of the zone ( returns 2 ZoneStates)
}}{{TableRowN| alarm_zone | unack_alarms | Optional | Array of ZoneState | Alarm states that are currently unacknowledged
}}{{TableEnd}}

====Example====
This example is requesting the '''devices_online''' and '''name''' values.

*'''Request JSON'''
{
"request_type": "read",
"resource": "dashboard",
"acctid": 12345678,
"session": "123a-456b-789c",
"dashboard": {
"online_count": null,
"device": [{
"name": null
}]
}
}

*'''Result JSON'''

{
"response": {
"dashboard": {
"device": [
{
"device_id": 9876,
"name": "A device"
},
{
"device_id": 5432,
"name": "Another device"
}
],
"online_count": 2
}
},
"result": {
"code": 0,
"message": "OK",
"success": true
}
}

Sensaphone.net API/login

2015-04-29T18:16:25Z

Mwood: /* Sensaphone.net API */ Update Session data type.

=[[Sensaphone.net API]]=

The Login API will be used to log in to the Sensaphone.net system. When a user logs in with their username and password they will be assigned a session UUID. The session UUID will have a corresponding time stamp and a timed expiration for their session. The session UUID and statically assigned Account ID will be used as the primary identifier instead of including a username and password in subsequent URI requests.

==Example Call==
https://rest.sensaphone.net/api/v1/login/{USERNAME}/{PASSWORD}

==Values==
*Username
*Password
*Session UUID
*Session Time stamp
*Session Expiration

==Example Requests==
===GET===
'''URI Mode Request URI's:'''
*Receive Login information
'''GET''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSION}/login
*Receive a Login timestamp for a session
'''GET''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSION}/login/login_timestamp
*Receive the number of seconds until a session expires
'''GET''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSION}/login/session_expiration

'''JSON MODE Request URI:'''
*Receive Login information
'''POST''' https://rest.sensaphone.net/api/v1/login

{{TableStart|border_size=1
}}{{TableRowN| '''Request Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN| acctid | Required | Integer | Static ID of user
}}{{TableRowN| session | Required | String | Session ID of user
}}{{TableEnd}}
 
{{TableStart|border_size=1
}}{{TableRowN| '''Response Property''' | '''Included''' | '''Type''' | '''Description'''
}}{{TableRowN| login_timestamp | Optional | String | Time stamp of last log in
}}{{TableRowN| session_expiration | Optional | Integer | Seconds until log in expiration
}}{{TableRowN| user_id | Optional | Integer | ID of the logged in user
}}{{TableEnd}}

====Example JSON====
Log in with a username and password using JSON mode.
*'''Request JSON:'''
{
"request_type":"create",
"resource": "login",
"user_name": "myusername",
"password": "pass123"
}

*'''Response JSON:'''
{
"result": {
"success": true,
"code": 0,
"message": "Success"
},
"response": {
"acctid": 987654,
"session": "0123-4567-8901",
"login_timestamp": 1499459402,
"session_expiration": 86400,
"user_id": 00000001
}
}

Receive Login information for a given session UUID.

*'''Request JSON:'''
{
"request_type:"read",
"resource":"login",
"acctid":987654,
"session":"0123-4567-8901",
"login":null
}

*'''Response JSON:'''
{
"result":
{
"success: true,
"code": 0,
"message":"OK",
},
"response":
{
"login_timestamp":"2014-12-31 23:59:59",
"session_expiration":60
}
}

===PUT===
PUT will be used only to update a Login session.

'''URI Mode Request URI:'''
*Request to update a Login session
'''PUT''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSION}/login
'''JSON Mode Request URI:'''
'''POST''' https://rest.sensaphone.net/api/v1/login

{{TableStart|border_size=1
}}{{TableRowN| '''Request Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN| acctid | Required | Integer | Static ID of user
}}{{TableRowN| session | Required | String | Session ID of user
}}{{TableRowN| user_name | Optional | String | Username
}}{{TableRowN| password | Optional | String | Password for username
}}{{TableEnd}}
 
{{TableStart|border_size=1
}}{{TableRowN| '''Response Property''' | '''Included''' | '''Type''' | '''Description'''
}}{{TableRowN| acctid | Conditionally* | Integer | Static ID of user
}}{{TableRowN| session | Conditionally* | String | Session ID of user
}}{{TableRowN| login_timestamp | Always | Integer | Time stamp of renewed session
}}{{TableRowN| session_expiration | Always | Integer | Time until new log in session expiration
}}{{TableRowN| user_id | Always | Integer | ID of the logged in user
}}{{TableEnd}}
<nowiki>*</nowiki> There may be an instance where the system needs to create a new Session ID and/or Account ID. In which case, it will be outputted in the PUT response.

===POST===
'''URI Mode Request URI:'''
*Request for creating a new login session
'''POST''' https://rest.sensaphone.net/api/v1/login/{USERNAME}/{PASSWORD}
'''JSON Mode Request URI:'''
'''POST''' https://rest.sensaphone.net/api/v1/login

{{TableStart|border_size=1
}}{{TableRowN| '''Request Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN| user_name | Required | String | Username
}}{{TableRowN| password | Required | String | Password for username
}}{{TableEnd}}
 
{{TableStart|border_size=1
}}{{TableRowN| '''Response Property''' | '''Type''' | '''Description'''
}}{{TableRowN| acctid | Integer | Static ID of user
}}{{TableRowN| session | String | Session ID of user
}}{{TableRowN| login_timestamp | Integer | Time stamp of renewed session
}}{{TableRowN| session_expiration | Integer | Time until new log in expiration
}}{{TableRowN| user_id | Integer | ID of the logged in user
}}{{TableEnd}}

===DELETE===
Deleting a login session is the equivalent to logging out.

'''URI Mode Request URI:'''
*Request to log out of a session
'''DELETE''' https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSION}/login
'''JSON Mode Request URI:'''
'''POST''' https://rest.sensaphone.net/api/v1/login

{{TableStart|border_size=1
}}{{TableRowN| '''Request Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN| acctid | Required | Integer | Static ID of user
}}{{TableRowN| session | Required | String | Session ID of user
}}{{TableEnd}}

==Future==
In the future the login process will support OAuth for advanced access and authentication.

==Password Reset==
To reset a pass for a particular email, use the following request:

'''POST''' https://rest.sensaphone.net/api/v1/login/reset_password/{email_address}

Sensaphone.net API

2015-04-29T18:04:35Z

Mwood: /* Resources */

==Overview==
The Sensaphone.net API will be used as a resource for proprietary products (such as mobile applications) and 3rd party clients. It uses a [[wikipedia:REST|REST]] architecture over HTTPS using JSON as the data format. HTTP is not supported. The service can be accessed in one of two modes: URI mode and JSON mode.

In '''''URI mode''''', the following HTTPS methods are used to access the REST resources as [[wikipedia:CRUD|CRUD]].
::{{TableStart|border_size=1
}}{{TableRowN| '''Method''' | '''Description'''
}}{{TableRowN| POST | '''C'''reate
}}{{TableRowN| GET | '''R'''ead
}}{{TableRowN| PUT | '''U'''pdate
}}{{TableRowN| DELETE | '''D'''elete
}}{{TableEnd}}
All parameters are specified in the URI and JSON is only used in the response.

In '''''JSON Mode''''', only the POST method is used to Create, Read, Update, and Delete fields. A "request_type"(create,read,update,delete) JSON property is used to distinguish which method to execute.

==Definitions==
:'''Resource''': A resource is a primary source of data. Examples: device, zone.
:'''Property''': A property is a discrete source of data within a resource (e.g. Device's name). A property may also be a resource (e.g. Device's zone).
:'''ID''': Resources have properties that uniquely identify them. For example, a device has a "device_id", a zone has a "zone_id". These identifying properties are optional or required (See [[#URI Syntax|URI Syntax]]) when accessing (read). They are required when modifying (update or delete) a specific existing resource. When creating they are required except for the resource being created. For a create, the newly created ID will typically be returned in the JSON result.

==URI Syntax==
The URIs are descriptive representations of what the client will receive as a response and will follow one of the formats:

/api/v1[/{''ACCTID''}/{''SESSIONID''}]/'''login'''/[/{''USERNAME''}/{''PASSWORD''}]
/api/v1[/{''ACCTID''}/{''SESSIONID''}][/'''Resource'''[/{''ID''}]]...[/'''Resource'''[/{''ID''}]]/'''Property'''[/{''VALUE''}]]
/api/v1[/{''ACCTID''}/{''SESSIONID''}][/'''Resource'''[/{''ID''}]]...[/'''Resource'''[/{''ID''}]]/'''Resource'''[/{''ID''}]]

NOTE: "v1" can be replaced with "v2","v3".

The "Resource" is the the name of the resource to be accessed (e.g. "device"). The "Property" used will be context dependent and is documented for each resource. Values are placed inside <nowiki>{}</nowiki> brackets. The brackets are used in the URI submitted.

In [[#Overview|URI Mode]], the Resource ID (e.g. "/''{ID}''") must be included unless it is the rightmost resource in the URI. In [[#Overview|JSON mode]], the ID is still required, but may be included in the submitted JSON instead.

Fields in <nowiki>[]</nowiki> brackets are optional on the URI, however, if they are required in the resource documentation, then they must be included '''either''' in the URI or in the JSON, but not both. The brackets themselves are not included in the URI submitted. Consider the following API call to retrieve the device name for device ID 1234:
'''URI Mode Request URI:'''
'''GET''' ''https://rest.sensaphone.net/api/v1/{987654}/{0123-4567-8901}/device/{1234}/name''
The ACCTID, SESSIONID, ID, and "name" fields may be excluded from the URI, but must then be included in the request JSON:
'''Request Description:'''
Retrieve the "name" property from device "1234".

'''JSON Mode Request URI:'''
'''POST''' ''https://rest.sensaphone.net/api/v1/device''

'''Request JSON:'''
{
"request_type:"read",
"resource":"device",
"acctid":987654,
"session": "0123-4567-8901",
"device": [
{
"device_id": 1234,
"name" : null
}
]
}

This will provide a response of the name of the device whose ID is "1234" for the account with ID 987654 using the Account ID of 987654 and Session ID of "0123-4567-8901":
'''Response JSON:'''
...
{
"device": [
{
"device_id": 1234,
"name" : "My Device"
}
]
}
...

The URI method is intended to allow quick access to single pieces of data, but using the JSON method is more complete and allows retrieval of multiple pieces of data at once.

===Additional Examples===
====POST====
'''Request Description:'''
Create a new alarm schedule for the device with ID 1234 and its zone with ID 112233.

'''URI Mode Request URI:'''
'''POST''' ''https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{1234}/zone/{112233}/alarmschedule

====GET====
'''Request Description:'''
Retrieve the name of the zone with ID 112233 of the device with ID 1234.

'''URI Mode Request URI:'''
'''GET''' ''https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{1234}/zone/{112233}/name

====PUT====
'''Request Description:'''
Change the name of the User with the ID 6778 to "John Doe".

'''URI Mode Request URI:'''
'''PUT''' ''https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{6778}/name/{John Doe}''

====DELETE====
'''Request Description:'''
Delete the User with the ID 6778.

'''URI Mode Request URI:'''
'''DELETE''' ''https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{6778}''

==JSON Format==
===Requests===
All requests using the JSON mode will only use the POST method with a "request_type" parameter.

All requests include one outer JSON object unless no request data is specified. Requests are made according the specific requirements of the resource being accessed. With the exception of the login page, a session ID must be included with all API requests. When using the [[#URI Syntax]] JSON mode, the following will be included:
{ ← All values must be within this outer JSON object.
"acctid":987654,
"session": "0123-4567-8901",
"request_type":"read", ← One of "read", "update", "create", "delete"
...
}

A resource is accessed as either a JSON array of objects or a JSON object. A resource's properties are listed in comma separated values in the JSON object for that resource. All JSON value types may be used. Resources within resources are accessed as JSON objects within objects (or Array of objects). The JSON type of a property is specified by the requirements for each resource.

When performing a '''Read''' on a resource, all properties will be returned if '''only''' the resource ID is specified. If one or more non-identifying properties are specified, only those properties will be returned. The data values for those ''specific'' properties should be 'null'.

When performing a '''Delete''', specified non-identifying properties to be deleted should have their data values set to 'null', just like in a '''Read'''.

When performing a '''Update''' or '''Create''', specified non-identifying properties to be set must have their data values set to valid types, '''not''' 'null'.

When performing a '''Update''', the identifying properties must be specified. You can't update a resource without identifying it.

When performing a '''Create''', the identifying properties of the resource being created should not be specified at all. Only existing resources can have identifiers already.

NOTE: Specifying properties that are not listed in the requirements has no effect.

'''JSON Mode Request URI:'''
'''POST''' ''https://rest.sensaphone.net/api/v1/device''

'''Request JSON:'''
{
"request_type":"read",
"resource":"device",
"acctid":987654,
"session": "0123-4567-8901", ← All values are within at least the outer JSON object.
"device":[ ← Devices are accessed as a JSON array of objects.
{
"device_id": 1234, ← The "device_id" property is provided to identify the device accessed.
"name": null, ← The "name" property is ''specifically'' requested, so it is set to null. The whole device will '''not''' be returned.
"zones":[ ← Zones are accessed as a JSON array of objects.
{
"zone_id": 112233 ← By only specifying the "zone_id" and no other properties, '''all''' zone data is requested.
}
],
"this fake property": "is ignored" ← Invalid properties are ignored.
}
]
}

The above request is equivalent to the following requests, but must be done in two steps because two pieces of data were requested (The device's name and the device's zone with the ID 112233). No request JSON is required in this case.
'''URI Mode Request URIs:'''
'''GET''' ''https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{1234}/name''
'''GET''' ''https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{1234}/zone/{112233}''

===Responses===
Responses conform to the following format and include error reporting.

{
"result":
{
"success": true, ← Overall result of the request.
"code": 0, ← Status code for overall result.
"message":"OK", ← String describing the overall result.

"properties": ← Optionally used for '''Create''', '''Update''', and '''Delete'''
{
"''PROPERTY''":{ ← Property names and layout will match the request.
"success": true,
"message":"OK",
"code":0
},
"''PROPERTY''":{
"success": false,
"message":"Failed",
"code":123
},
...
},
},
"response": ← Any data that may have changed ('''Create'''/'''Update'''/'''Delete''') or been requested ('''Read''').
{
...
}
}

The success, code, and message for the overall result will always be included. The data in the "response" JSON object will depend on the specification of the resource accessed in the original request, but will generally follow the same layout and format of the request, although the specific properties returned will vary.

'''JSON Mode Request URI:'''
'''POST''' ''https://rest.sensaphone.net/api/v1/device''

'''Request JSON:'''
{
"request_type":"update",
"resource":"device",
"acctid":987654,
"session": "0123-4567-8901",
"device":[
{
"device_id": 1234,
"name": "My Device", ← The device's "name" property is being changed.
"zone":[
{
"zone_id": 112233,
"name": 1234 ← The device's zone's "name" property is being changed.
}
]
}
]
}

'''Response JSON:'''
{
"result":
{
"success": true, ← The overall request was processed correctly, even if some properties had errors.
"code": 0,
"message":"OK",

"properties":
{
"device":[
{
"device_id": 1234, ← Identifying properties must be specified.
"name": { ← Property "name" was changed.
"success": true,
"message":"OK",
"code":0
},
"zone":[
{
"zone_id": 112233, ← Identifying properties must be specified.
"name": { ← The device's zone's "name" was changed.
"success": false,
"message": "A string type is required",
"code":123
}
}
]
}
]
},
},
"response":
{
"device":[
{
"device_id": 1234, ← Identifying properties must be specified.
"name": "My Device", ← The new value for the device's "name".
}
]
}
}

The above request is equivalent to the following requests, but must be done in two steps because two pieces of data were updated (The device's name and the device's zone's name). No request JSON is required in this case.
'''URI Mode Request URIs:'''
'''PUT''' ''https://rest.sensaphone.net/api/v1/{987654}/{0123-4567-8901}/device/{1234}/name/{My Device}''
'''PUT''' ''https://rest.sensaphone.net/api/v1/{987654}/{0123-4567-8901}/device/{1234}/zone/{112233}/name/{1234}''

The following are some of the status codes used for overall status.
::{{TableStart|border_size=1
}}{{TableRowN| '''Code''' | '''Description'''
}}{{TableRowN| 0 | Success
}}{{TableRowN| 1 | Failed: No Session ID provided
}}{{TableRowN| 2 | Failed: Session ID has expired
}}{{TableRowN| 3 | Failed: Invalid request URI.
}}{{TableRowN| 4 | Failed: Invalid request JSON.
}}{{TableRowN| 5 | Failed: Invalid username provided.
}}{{TableRowN| 6 | Failed: Invalid password provided.
}}{{TableRowN| 7 | Failed: User is not authorized.
}}{{TableRowN| 8 | Failed: Service unavailable. Try again later.
}}{{TableEnd}}

==Versions==
There will be three versions of the API. We will refer to them as V1, V2, and V3. The only difference between the versions is in the format of '''responses'''. Requests to the Sensaphone.net API are identical in all cases.

===V1===
V1 will primarily be used to give responses that will be directly displayed in a client's application.

'''Example V1 Response for "https://rest.sensaphone.net/api/v1/{987654}/{0123-4567-8901}/device/{1234}/name" :'''

{
"device": [
{
"device_id": 1234,
"name" : "My Device"
}
]
}

===V2===
V2 should be used when responses with the addition of metadata are needed.

'''Example V2 Response for "https://rest.sensaphone.net/api/v2/{987654}/{0123-4567-8901}/device/{1234}/name" :'''
{
"device": [
{
"device_id": 1234,
"name":
{
"is_null" : false,
"is_empty": false,
"value" : "Device 1",
"type" : "string",
"is_pending": false,
"is_ranged" : true,
"ranged":[
{
"null": false,
"min" : 0,
"max" : 128
}
]
}
}
]
}

::{{TableStart|border_size=1
}}{{TableRowN| '''Property''' | '''Status''' | '''Type''' | '''Description'''
}}{{TableRowN| is_null | Required | Boolean | States if the corresponding value is NULL. If so, no additional keys are given.
}}{{TableRowN| is_empty | Required* | Boolean | States if the corresponding value is empty. If so, no additional keys are given.
}}{{TableRowN| value | Required** | String | Description of the corresponding value
}}{{TableRowN| type | Required** | String | Type of value
}}{{TableRowN| is_pending | Optional | Boolean | States if the value is in process of being updated
}}{{TableRowN| is_ranged | Optional | Boolean | States if there is a set of ranges for the value
}}{{TableRowN| ranged | Optional | Array | Array of ranges
}}{{TableRowN| → null | Required | Boolean | States if the value can be null.
}}{{TableRowN| → min | Required*** | Mixed | Min of range
}}{{TableRowN| → max | Optional | Mixed | Max of range
}}{{TableEnd}}
::<nowiki>*</nowiki> Only required if "is_null" is false.
::<nowiki>**</nowiki> Only required if "is_empty" is false.
::<nowiki>***</nowiki> Only required if "null" is false.

===V3===
V3 should be used when only the pending meta data is needed

'''Example V3 Response for "https://rest.sensaphone.net/api/v3/{987654}/{0123-4567-8901}/device/{1234}/name" :'''

{
"device": [
{
"device_id": 1234,
"name" :
{
"is_pending": true
}
}
]
}

==Resources==
The following resources are accessible through the REST API. They may be accessible from different URI contexts. See the individual resource pages for more information.

'''All REST requests should be made against https://rest.sensaphone.net'''

::{{TableStart|border_size=1
}}{{TableRowN|'''Page''' |'''GET'''|'''PUT'''|'''POST'''|'''DELETE'''
}}{{TableRowN|  |(Read)|(Write)|(Create)|(Delete)
}}{{TableRowN|[[{{PAGENAME}}/login|login]] |Y|Y|Y|Y
}}{{TableRowN|[[{{PAGENAME}}/dashboard|dashboard]] |Y|N|N|N
}}{{TableRowN|[[{{PAGENAME}}/history|history]] |Y|N|N|N
}}{{TableRowN|[[{{PAGENAME}}/account|account]] |Y|Y|N|N
}}{{TableRowN|[[{{PAGENAME}}/feature|feature]] |Y|Y|N|N
}}{{TableRowN|[[{{PAGENAME}}/device|device]] |Y|Y|Y|Y
}}{{TableRowN|[[{{PAGENAME}}/devicegroup|devicegroup]] |Y|Y|Y|Y
}}{{TableRowN|[[{{PAGENAME}}/address|address]] |Y|Y|N|N
}}{{TableRowN|[[{{PAGENAME}}/coordinates|coordinates]] |Y|Y|N|N
}}{{TableRowN|[[{{PAGENAME}}/zone|zone]] |Y|Y|Y|N
}}{{TableRowN|[[{{PAGENAME}}/calllist|calllist]] |Y|Y|Y|Y
}}{{TableRowN|[[{{PAGENAME}}/alarmschedule|alarmschedule]] |Y|Y|Y|Y
}}{{TableRowN|[[{{PAGENAME}}/schedule|schedule]] |Y|Y|Y|Y
}}{{TableRowN|[[{{PAGENAME}}/timerange|timerange]] |Y|Y|Y|Y
}}{{TableRowN|[[{{PAGENAME}}/contactgroup|contactgroup]] |Y|Y|Y|Y
}}{{TableRowN|[[{{PAGENAME}}/user|user]] |Y|Y|Y|Y
}}{{TableRowN|[[{{PAGENAME}}/contact|contact]] |Y|Y|Y|Y
}}{{TableEnd}}

===List===
The following is a list of all possible REST resources, excluding any possible '''<nowiki>[/Property/[/Value]]</nowiki>''' suffix. Properties ('''/Property''') of a resource are shown where it is a JSON object or array of objects (e.g. "alarmschedule"). For a full list of properties and values associated with each resource, see the page for that resource.
*/api/v1/login/{USERNAME}/{PASSWORD}
*/api/v1/{ACCTID}/{SESSIONID}/account
*/api/v1/{ACCTID}/{SESSIONID}/account/feature
*/api/v1/{ACCTID}/{SESSIONID}/calllist
*/api/v1/{ACCTID}/{SESSIONID}/contact
*/api/v1/{ACCTID}/{SESSIONID}/contact/schedule
*/api/v1/{ACCTID}/{SESSIONID}/contact/schedule/timerange
*/api/v1/{ACCTID}/{SESSIONID}/contactgroup
*/api/v1/{ACCTID}/{SESSIONID}/dashboard
*/api/v1/{ACCTID}/{SESSIONID}/device
*/api/v1/{ACCTID}/{SESSIONID}/device/default_schedule
*/api/v1/{ACCTID}/{SESSIONID}/device/default_schedule/timerange
*/api/v1/{ACCTID}/{SESSIONID}/device/default_schedule/calllist
*/api/v1/{ACCTID}/{SESSIONID}/device/device_schedule
*/api/v1/{ACCTID}/{SESSIONID}/device/device_schedule/timerange
*/api/v1/{ACCTID}/{SESSIONID}/device/device_schedule/calllist
*/api/v1/{ACCTID}/{SESSIONID}/device/feature
*/api/v1/{ACCTID}/{SESSIONID}/device/location
*/api/v1/{ACCTID}/{SESSIONID}/device/location/address
*/api/v1/{ACCTID}/{SESSIONID}/device/location/coordinates
*/api/v1/{ACCTID}/{SESSIONID}/device/zone
*/api/v1/{ACCTID}/{SESSIONID}/device/zone/alarm_zone/alarmschedule
*/api/v1/{ACCTID}/{SESSIONID}/device/zone/alarm_zone/alarmschedule/timerange
*/api/v1/{ACCTID}/{SESSIONID}/device/zone/alarm_zone/alarmschedule/calllist
*/api/v1/{ACCTID}/{SESSIONID}/device/zone/schedule
*/api/v1/{ACCTID}/{SESSIONID}/device/zone/schedule/timerange
*/api/v1/{ACCTID}/{SESSIONID}/devicegroup
*/api/v1/{ACCTID}/{SESSIONID}/history
*/api/v1/{ACCTID}/{SESSIONID}/login
*/api/v1/{ACCTID}/{SESSIONID}/user
*/api/v1/{ACCTID}/{SESSIONID}/user/alarm_user/contact
*/api/v1/{ACCTID}/{SESSIONID}/user/alarm_user/contact/schedule
*/api/v1/{ACCTID}/{SESSIONID}/user/alarm_user/contact/schedule/timerange
*/api/v1/{ACCTID}/{SESSIONID}/user/alarm_user/schedule
*/api/v1/{ACCTID}/{SESSIONID}/user/alarm_user/schedule/timerange
*/api/v1/{ACCTID}/{SESSIONID}/user/site_user/address

==FAQ==
Visit our [[FAQ|Frequently Asked Questions]] page.

==Help==
If you need help using our API and your question isn't answered in the wiki, please feel free to email us at: [mailto:api@sensaphone.net api@sensaphone.net]

Main Page

2015-03-24T20:08:00Z

Mwood:

To access your devices and accounts on the Sensaphone.net website please go to:
[https://www.sensaphone.net www.sensaphone.net]

REST API Frequently Asked Questions:
[[FAQ|FAQ]]

Access the Sensaphone.net REST API documentation:
[[Sensaphone.net API|Documentation]]