With the release of v2.0.0, all SmartBuildings API users can now control even more settings on individual thermostats, including comfort settings, configuration settings, access settings, and the schedule. Breaking changes include changes to residentMode, acMaintenanceReminder, heat/cool setpoints and introduction of a new v2 token endpoint. The newly released bulk endpoint /api/v2/thermostats/settings allows you to update configuration settings across up to 25 thermostats at once.

Here is an overview of the updates introduced in the v2.0.0 API. Please refer to the API reference for the full details.

Breaking Changes

Resident mode

Tenant mode has been renamed to resident mode, and the associated endpoints and payload fields have been updated.

• PATCH /api/v2/thermostats/{thermostatId}/tenantMode is now PATCH /api/v2/thermostats/{thermostatId}/residentMode.
  • Now takes a payload with an isResidentMode field.
• GET /api/v2/thermostats/{thermostatId}/status
  • Now returns isResidentMode in the response payload.
• POST /api/v2/thermostats/{buildingId}/thermostats
  • Now takes a payload with an isResidentMode field.

AC maintenance reminder field removed

AC maintenance reminders are not implemented on the thermostat, so the field has been removed from the API. HVAC maintenance reminders should be used instead.

GET /api/v2/thermostats/{thermostatId}/alertSettings

• Will no longer include acMaintenanceReminder in the response payload.

PATCH /api/v2/thermostats/{thermostatId}/alertSettings

• Will no longer accept acMaintenanceReminder in the request payload. To set maintenance reminders, include a configuration for hvacMaintenanceReminder.

Setpoints in heat and cool mode

Previously, the API returned different values for the heat and cool setpoints depending on the HVAC mode. This made it difficult to determine both setpoints after switching to auto mode, since the mode change can take a few seconds to be reflected in the API response. Now the true heat and cool setpoints are always returned, regardless of mode.

In v1, GET /api/v2/thermostats/{thermostatId}/status previously returned values as indicated below:

heat or auxHeatOnly mode:

{
  ...
  "setPoint": {
    "desiredHeat": <heat setpoint>,
    "desiredCool": <heat setpoint>
  }
}

cool mode:

{
  ...
  "setPoint": {
    "desiredHeat": <cool setpoint>,
    "desiredCool": <cool setpoint>
  }
}

auto mode:

{
  ...
  "setPoint": {
    "desiredHeat": <heat setpoint>,
    "desiredCool": <cool setpoint>
  }
}

off mode:

{
  ...
  "setPoint": {}
}

In v2, GET /api/v2/thermostats/{thermostatId}/status returns the following values no matter which mode

{
  ...
  "setPoint": {
    "desiredHeat": <heat setpoint>,
    "desiredCool": <cool setpoint>
  }
}

What's New?

Token endpoint

GET /api/v2/token

• Token fetching should be updated to fetch from /api/v2/token.

View Thermostat schedule endpoint

GET /api/v2/thermostats/{thermostatId}/schedule

• Displays what the weekly schedule looks like for the thermostat, to each half hour interval.

View Thermostat comfort settings endpoint

GET /api/v2/thermostats/{thermostatId}/comfortSettings

• Displays a named comfort setting for your thermostat.
  • Comfort setting will contain name, desiredHeat, desiredCool, fanHeat, and fanCool.

View Thermostat configuration settings endpoint

GET /api/v2/thermostats/{thermostatId}/settings

• View heat/cool ranges and fan settings for the thermostat.
  • Contains heatRange/coolRange with min/max values, holdAction, fanMinimumOnTime

Create Thermostat comfort settings endpoint

POST /api/v2/thermostats/{thermostatId}/comfortSettings

• Create a new comfort setting to be used in the schedule.
  • Comfort setting will contain name, desiredHeat, desiredCool, fanHeat, and fanCool.

Update Thermostat access settings endpoint

PATCH /api/v2/thermostats/{thermostatId}/accessControl

• Update access control settings for a thermostat.
• Can be toggled true or false
  • If true, can provide a numeric 4 digit passcode, settings containing booleans oftemperature, systemMode, schedule, vacation, other

Update Thermostat configuration settings endpoint

PATCH /api/v2/thermostats/{thermostatId}/settings

• Update heat/cool ranges and fan settings for the thermostat.
  • Contains heatRange/coolRange with min/max values, holdAction, fanMinimumOnTime

Update Thermostat comfort settings endpoint

PATCH /api/v2/thermostats/{thermostatId}/comfortSettings

• Update an existing comfort setting.
  • Editable fields are name, desiredHeat, desiredCool, fanHeat, and fanCool.

Delete Thermostat comfort settings endpoint

DELETE /api/v2/thermostats/{thermostatId}/comfortSettings/{comfortSettingRef}

• Delete an existing comfort setting.

Update Thermostat schedule endpoint

PATCH /api/v2/thermostats/{thermostatId}/schedule

• Update your thermostat schedule with a provided range and comfort setting.
  • Schedule is set by days, firstTimeBlock, lastTimeBlock, comfortSettingRef

Bulk update Thermostats configuration settings endpoint

PATCH /api/v2/thermostats/settings

• Bulk update the heat/cool ranges and fan settings for up to 25 thermostats.
• Contains heatRange/coolRange with min/max values, holdAction, fanMinimumOnTime

Update Thermostat building

PATCH /api/v2/thermostats/{thermostatId}

• Added ability to move a thermostat to a new building