Wally API Documentation

API Introduction

The WallyHome API is a RESTful service that provides a mechanism for retrieving sensor data programmatically. The API returns JSON that reports each sensor's temperature, humidity, and any active events (e.g., a leak). In the WallyHome web app settings page, users can:

  • Retrieve an OAuth2 token for making authenticated requests
  • Register up to three callback URLs to subscribe to events

How to use the WallyHome API

Before using the WallyHome API, you will need to set up an account and install the hub and sensors so that you will have a stream of sensor data to access. Once the system is set up:

  1. Retrieve the OAuth2 token from the settings page and include it in all of your client's REST calls with a header similar to: "Authorization:Bearer <token>", where <token> is the retrieved OAuth2 token.
  2. Make the appropriate REST calls using the API access URL: https://api.snsr.net/
  3. Enter desired callback URLs on the settings page if event notifications are desired.

About the Data Model

Your clients will receive sensor data and active events in JSON format.

About Security

All of our communication is secured via SSL. As the account owner, you always explicitly grant permission to access data, and you may revoke that access at any time.

We use OAuth 2.0 for authorization. OAuth is a means to securely create a trust agreement between a resource owner (a WallyHome user), a client (an application or service developed by you) and a resource server (WallyHome's API servers).

Property Information

GET /v2/places

Sample Response:

[ { "id": "abcdef01234",
This is a unique property identifier; its value <id> is used in the subsequent GET /v2/places/<id>/sensors call to retrieve sensors from this property
"accountId": "000-111-222-3333-44-5555",
This is a unique account identifier.
"label": "Wally Labs",
Name of property corresponding to <id>
"fullAddress": { "line1": "Office", "line2": "1415 NE 45th St", "city": "Seattle", "state": "WA", "zip": "98105" }, "address": "Office, 1415 NE 45th St, Seattle, WA 98105", "suspended": false,
Reporting state of the property; if true, all messages from this property should be suppressed
"buzzerEnabled": true,
Reporting state of the Hub's buzzer; if true, Hub will buzz during an alarm event.
"sensorIds": ["90-7a-f1-ff-ff-ff"],
Collection of sensors (ids) in the property.
"nestAdjustments": {}, "nestEnabled": true,
Property contains a nest thermostat.
"rapidResponseSupport": ["rapidResponseSupport"]
If not empty; property belongs to a zipcode that supports Wally Rapid Response.
} ]

Sensor Information

GET /v2/places/<id>/sensors
Using the <id> value from the GET /v2/places/ call, this returns information about all sensors installed in property corresponding to <id>

Sample Response:

[ { "snid": "90-7a-f1-ff-ff-ff",
Serial number of sensor
"offline": false,
State of sensor; if "offline", sensor has not been heard for over 24 hours
"suspended": false,
Reporting state of the sensor; if true, all messages form this sensor should be suppressed
"paired": 2016-07-06T17:11:58.001Z,
Time event when sensor was successfully paired, in UTC.
"updated": 2016-07-06T20:48:35.872Z,
Time event when sensor was updated, in UTC.
"alarmed": false,
Reports water leak detection.
"signalStrength": 0,
Reports signal strenght for "WaterSensor" type sensors.
"recentSignalStrength": 55.737163247999995, "hardwareType": "FourInOneSensor",
Reports sensor type; FourInOneSensor or WaterSensor;
"location": { "id": "00003bd0c9e77c0021fc60e1", "placeId": "abcdef01234", "sensorId": "90-7a-f1-ff-ff-ff", "room": "Kitchen", "appliance": "Sink", "floor": "Main Floor", "functionalType": "LEAK", "created": "2016-07-06T17:11:44.926Z", "updated": "2016-07-06T17:11:44.920Z" }, "thresholds": { "TEMP": { "name": TEMP, "min": 10,
Temperature minimum set threshold, in Fahrenheit
"max": 38
Temperature maximum set threshold, in Fahrenheit
}, "RH": { "name": RH, "min": 30
Humidity minimum set threshold, in %
} }, "state": { "RH": { "value": 56,
Relative humidity sensed, in %
"at": "2016-07-06T20:48:35.315Z"
Time of sensing, in UTC
}, "TEMP": { "value": 21,
Temperature sensed, in Celsius
"at": "2016-07-06T20:48:35.315Z"
Time of sensing, in UTC
} "LEAK": { "value": 0,
Water leak detected if value equals 15, Dry if value is less than 15.
"at": "2016-07-06T20:48:35.315Z"
Time of sensing, in UTC
}, "SENSOR": { "value": 0,
0 for water sensor or 1 as contact sensor
"at": "2016-07-06T20:48:35.315Z"
Time of sensing, in UTC
}, "COND": { "value": 0,
Magnet close to sensor if value is less than 15, open if value equals 15.
"at": "2016-07-06T20:48:35.315Z"
Time of sensing, in UTC
}, }, "activities": [ { "snid": "90-7a-f1-ff-ff-ff",
Serial number of sensor
"created": "2014-10-13T21:37:36.472Z",
Time event started, in UTC
"type": "alarm",
Type of events: alarm(leak), button_press_paired, dead_sensor, dead_gateway, rh_too_high, rh_too_low, temp_too_high, temp_too_low, mold_risk
"state": "open",
State of event; if "open" user has not acknowledged event, "acknowledged" if user has acknowledged event, "resolved" if the event has been resolved
"viewParams": { "floor": "Main Floor", "location": "Main Floor Kitchen Sink", "label": "Wally Labs", "appliance": "Sink", "room": "Kitchen" } } ] } ]

Callback URLs will receive a POST with the event data (see sample below) when a new event happens, or when an existing event's state changes.

{ "snid": "90-7a-f1-ff-ff-ff",
Serial number of sensor
"created": "2014-10-13T21:37:36.472Z",
Time event started, in UTC
"type": "alarm",
Type of events: alarm(leak), button_press_paired, dead_sensor, dead_gateway, rh_too_high, rh_too_low, temp_too_high, temp_too_low, mold_risk
"state": "open",
State of event; if "open" user has not acknowledged event, "acknowledged" if user has acknowledged event, "resolved" if the event has been resolved
"viewParams": { "floor": "Main Floor", "location": "Main Floor Kitchen Sink", "label": "Wally Labs", "appliance": "Sink", "room": "Kitchen" } }