How can we help?
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. |