How can we help?
Print

Thermostat

Thermostat attributes allow you to set and retrieve thermostat configurations and active statuses.

Thermostat - Reserved versus User Defined Attributes

There are two types of attributes supported for “Thermostat” objects. The first type are listed below, which are reserved and predefined. In addition to the predefined attributes, users can define, set and retrieve their own attributes. Any attribute name which is not reserved will be treated like a User Defined Attribute. Defining an new attribute is accomplished by setting its value through a SET request. Once SET, these attributes can be accessed using GET requests. Their is no restriction on the number of user defined attributes or their values. User defined attributes can also be used as part of the selection criteria. For example, if the user wants to manage a group of thermostats through the API, they could define an attribute named “managed” and SET its value to “yes” for the thermostats in the user's group. Then they could include “managed:yes;” in their selection criteria to only affect their special group of thermostats.

Thermostat - Object Attributes

Attribute names are not case sensitive. Attribute values are case sensitive.

Name Values Settable Description
name String Yes The configured name of the thermostat.
groupName String Yes The configured group name for that thermostat.
serialNo String No The thermostat's serial number. Unique factory set identifier.
system Off, Auto, Heat, Cool Yes The thermostat's active system mode
heatSetting Integer Yes The thermostat's active Heat Setting.
coolSetting Integer Yes The thermostat's active Cool Setting.
fan Auto, On Yes The thermostat's active Fan Mode.
status Occupied, Vacant Yes Normally Occupied. Vacant when vacation schedule is active.
temperature Decimal No The thermostat's current measured temperature.
humidity Integer No The thermostat's current measured humidity: % RH. Zero (0) if humidity is not supported.
humidifySetting Integer Yes The thermostat's minimum humidity setting.
dehumidifySetting Integer Yes The thermostat's maximum humidity setting.
co2Setting Integer Yes The thermostat's demand ventilation CO2 setting.
co2Level Integer No The thermostat's current measured CO2 level.
setBy Station, Remote, Schedule No Indicates how the active thermostat settings were set.
frontKeypad On, Off Yes Thermostat keypad active or locked status. On = Unlocked, Off = Locked.
outsideVentilation On, Off Yes Whether the thermostat is allowed to use Outside Ventilation.
runStatus Off, Cool-Stage1, Cool-Stage2, Heat-Stage1, Heat-Stage2, Fan, Fan2 No The currently active Fan, Heat or Cool status
statusDisplay String No Easily readable indication of what is currently active the or response “Unreachable” will be provided if the thermostat is unable to reach the Internet.
auxStatus On, Off No The thermostat's active Auxiliary Heat status.
slaves Array No List of the remote temperature sensors and devices assigned to this thermostat and their values.
description String Yes Free form thermostat description with configuration.
cycleRate Integer Yes Thermostat's c onfigured target cycle rate.
anticipationDegrees Decimal Yes Thermostat's configured anticipation degrees.
calibrationOffset Decimal Yes Thermostat's configured calibration degrees.
heatStages Integer Yes Number of configured heat stages.
coolStages Integer Yes Number of configured cool stages.
fanStages Integer Yes Number of configured fan stages.
HeatNeedsFan Yes, No Yes Enable Fan (G output) during heating.
temperatureFormat Fahrenheit, Celsius Yes Thermostat's active temperature format.
systemType Conventional, Heat Pump Yes Thermostat's configured system type.
reversingValve String Yes One of: Heat or Cool. Energizes reversing valve in this mode. Only valid for systemType of Heat Pump.
minHeatSetting Integer Yes Configured lowest allowable user settable heat set point.
maxHeatSetting Integer Yes Configured highest allowable user settable heat set point.
minCoolSetting Integer Yes Configured lowest allowable user settable cool set point.
maxCoolSetting Integer Yes Configured highest allowable user settable cool set point.
fanCirculationTime Integer Yes Configured enforced minimum minutes to run the fan across each hour.
heatingType String Yes Configured size of first stage heating system.
heating2Type String Yes Configured size of second stage heating system.
coolingType String Yes Configured size of first stage cooling system.
cooling2Type String Yes Configured size of second stage cooling system.
humidityControl String Yes One of: None, Humidify, Dehumidify, Full Control, Cool Only.
minSafeHumidity Integer Yes Lowest allowed thermostat relative humidity reading before notification is sent.
maxSafeHumidity Integer Yes Highest allowed thermostat relative humidity reading before notification is sent.
allowKeypadDisable Yes, No Yes Display the configuration Lock Keypad On/Off button in the thermostat's configuration.
weight Integer Yes Weighted value of the thermostat's temperature reading when used with Remote Sensors
notificationSensitivity String Yes One of: Off, Low, Medium, High, Custom. Note: When setting Custom notificationSetpoint and notificationUnreachable should also be set.
notificationSetpoint Integer Yes The temperature degrees from the thermostat's setpoint before sending a notification. Forces notificationSensitivity to Custom.
notificationUnreachable Yes, No Yes Send a notification if thermostat becomes unreachable for 4 hours. Forces notificationSensitivity to Custom.
minSafeTemp Integer Yes Lowest allowed thermostat temperature reading before a notification is sent.
maxSafeTemp Integer Yes Highest allowed thermostat temperature reading before a notification is sent.
gateway String No The serial number of the gateway providing Internet access to this thermostat.
version String No The thermostat's firmware version.
installDate Date/Time No ISO 8601 Formatted Date Time indicating when the thermostat was first installed at the site.
schedule On, Off, Name Yes Whether the thermostat's schedule is active or the Name of the shared schedule.
scheduleName String Yes If the thermostat is using a Shared Schedules, the name of the active schedule.
scheduleRepeat Daily, Weekday, Weekly Yes How the thermostat's schedule is set to repeat.
setback On, Off Yes Whether a temporary Demand Response setback is active.