Change Log

Noteworthy changes and updates to the API or documentation.

August 2020

  • Added notice of upcoming changes regarding authorization flows and access/refresh token format changes. More information can be found at the Developer App Migration Strategy docs.

May 2019

  • Rate restrictions currently apply to all API integrations. Integrators will be notified automatically when exceeding the rate limit through an "HTTP 429 Error: Too Many Requests" response status code.
  • The lightly-used /demandManagement endpoint will be deprecated.
  • Runtime reports provide the historical runtime information for a selection of thermostats. The /runtimeReport endpoint (in which runtime data is returned as JSON and is capped at 25 thermostats per request) will no longer be made available through the Utility API. However, the same data will remain available through the /runtimeReportJob which has many advantages over /runtimeReport, such as the ability to request an entire management set in CSV format.

May 2018

June 2017

  • Added new model numbers for ecobee4 thermostat (apolloSmart, apolloEms) to Thermostat modelNumber field.
  • Added new property to the Selection object. Selection.includeAudio allows to read Audio settings for the thermostat.
  • Added new Audio object. Audio settings allow to change volume of internal speaker (if applicable), turn on or off privacy mode (if applicable) and list available voice engines.
  • Added new VoiceEngine object
    • .
  • Added functionality to unlink voice engine. See UnlinkVoiceEngine function.
  • Properties Settings.soundTickVolume and Settings.soundAlertVolume are deprecated.

April 2017

  • Added new asynchronous API for utilities that relaxes the limits imposed by the current Runtime Report API (see the Getting Started page for the Downloadable Runtime Report API).

May 2016

  • Added two fields to the Runtime object. Runtime.desiredHeatRange and Runtime.desiredCoolRage can be queried to determine the valid set point ranges for heating and cooling. Recommended use is to query these values before calling the SetHold Function. The values of a hold will be silently adjusted to the limits of the desired temperature range as dictated by the active DemandResponse, if they exceed those limits.
  • Updated the SetHold Function to enforce the DemandResponse.endTime and DemandResponse.endTime on any hold which is set when there is a currently active DemandResponse.

December 2015

  • Revamped API Documentation - Updated styling, added Examples section, added search bar, added sample API calls on every request page.
  • Added brand and features to Thermostat object. See Thermostat Brands and Features for more information.
  • Fixed an issue where the user had to include Event.coolHoldTemp and Event.heatHoldTemp values on a DemandResponse request even if the Event.isAbsolute field was false. These fields are no longer mandatory unless Event.isAbsolute is true. See the Event object for more information.
  • Updated the Licensing Agreement. See the Licensing Agreement for more information.
  • Corrected documentation involving the response field 'expires_in'. The value for this should be in seconds, not minutes. See Refreshing Your Tokens for more information.

March 2015

  • Fixed typo in OAuth endpoint error response, error_description field name. See Errors section for updated information.
  • Exposed the remote sensors through the API. Remote Sensor data is retrieved using new includeSensors option in the Selection object.
  • Added functionality to allow specific sensors to be used in specific climates. See Climate.
  • Added a thermostat function to update the ecobee3 remote sensor. See UpdateSensor function for more information.
  • Added ability to resume all events and return the thermostat to its program by providing resumeAll flag in the ResumeProgram function.

September 2014

  • Updated the response to the Groups POST request so that it includes the groups that were created/modified.
  • Added a thermostat function to reset the user configurable preferences. See Reset Preferences function for more information.

July 2014

  • Added a new revision to the Thermostat Summary called IntervalRevision which differs from RuntimeRevision in that the runtime revision is the revision of all the runtime information combined, whereas the interval revision only changes when the thermostat transmits its 15 minute interval status message to the server. The runtime revision behaviour remains as it was previously. Runtime revision will be updated when the thermostat sends the interval status message every 15 mins as well as whenever the equipment state changes on the thermostat and it transmits that information. The equipment message can come at a frequency of 3 mins. Since some users reported that they were getting false positives on the runtime revision due to equipment state updates, we added a new interval revision to segregate these updates and make it more clear when the full runtime state of the thermostat has changed.
  • Added additional fields to Runtime and ExtendedRuntime: runtimeDate and runtimeInterval. These fields will enable you to align the runtime data precisely with the Runtime Report data and remove any ambiguity of which 5 minute interval the data fits into.
  • Exposed new fields in the Setting object: ventilatorFreeCooling, dehumidifyWhenHeating, and ventilatorDehumidify.
  • Exposed new field in the House Details object of the Thermostat named windowEfficiency, used to define the efficiency of the home windows. Changing the value of this field alters the settings the thermostat uses for the humidifier when in 'frost Control' mode.
  • Exposed the SecuritySettings object of the Thermostat so those fields can be retrieved and updated through the API. Retrieved by setting the includeSecuritySettings flag to true in the GET Thermostat request Selection object.
  • Updated the userAccessCode and userAccessSetting fields of the Settings object of the Thermostat to be read only. Those fields can now only be set via the SecuritySettings object.

June 2014

  • Added Register Account for registration of Si model thermostats through the API.
  • Exposed the House Details object of the Thermostat so those fields can be retrieved and updated through the API. Retrieved by setting the includeHouseDetails flag to true in the GET Thermostat request Selection object.
  • Thermostat program updates can now handle the addition, update and deletion of climates. You may not delete the default 4 climates (Smart), 3 climates (ecobee3), nor the default 2 climates (EMS).
  • Added a new API error code to indicate when a user has de-authorized the app and/or de-registered their account.
  • Exposed new fields of the Settings object. The new fields are: ventilatorMinOnTimeHome, ventilatorMinOnTimeAway, backlightOffDuringSleep, autoAway, smartCirculation, followMeComfort, ventilatorType, isVentilatorTimerOn, ventilatorOffDateTime, hasUVFilter and coolingLockout.
  • Added a new field to the Event object: holdClimateRef
  • Added a new field to the Thermostat object through the API, equipmentStatus. Updated the Selection object to allow this data to be queried.
  • Updated the /thermostatSummary request and response to return the equipment status if the Selection has includeEquipmentStatus = true.
  • Added a new field to the Alert object through the API, notificationType - possible values are alert, hvac, furnaceFilter, humidifierFilter, dehumidifierFilter, ventilator, ac, airFilter, airCleaner, uvLamp, temp, lowTemp, highTemp, lowHumidity, highHumidity, auxHeat, auxOutdoor.
  • Added new requests for getting and updating the Groups and Group Settings. This is only available to the home user and not visible to the utilities. See GET Group request and POST Group request for more information.
  • Exposed the NotificationSettings object of the Thermostat so those fields can be retrieved and updated through the API. Retrieved by setting the includeNotificationSettings flag to true in the GET Thermostat request Selection object.
  • Updated the /registerAccount request to handle passing the User's first name and last name when making the register call.
  • Exposed a new Event type template that reflects the User's preferred vacation event default settings
  • Updated the possible values for the Settings.holdAction field. The list of possible values is now: useEndTime4hour, useEndTime2hour, nextPeriod, indefinite, askMe.
  • Updated the possible values for the Settings.dehumidifierMode field. The list of possible values is now: on, off.
  • Exposed the thermostat Version object.
  • Exposed the dehumidifyOvercoolOffset field in the Setting object and the logic relating to the dehumidifyWithAC field.

August 2013

  • Fixed an issue where multiple installations of the same AppKey for the same user on different devices clobbered each other's access/refresh tokens.
  • Refresh tokens will now not expire 14 days after first or until the associated access token is first used. This resolves an issue if for some reason you did not receive a reply with the tokens and the refresh token was immediately expired.
  • The Issue Demand Response response will now contain the demandResponseRef for the DR just issued. The unique ID is required to cancel the DR.
  • Fixed an issue where issued DRs did not appear in the utility web portal Manage Events widget. Unfortunately the fix is not retroactive for already issued DRs.
  • Added new GET List Demand Response to list all DRs which have not expired yet.
  • Added clarifications and updates to Management Hierarchy documentation.
  • Added requests which permit programmatic control of management hierarchies: users, thermostats and privileges for both EMS and Utility accounts. See the Making Requests section under Hierarchy
  • Re-organized the request navigation by logical function rather than GET/POST categories.

June 2013

  • Beta has ended! Your applications may now be authorized by all users.
  • Added a new Support section.
  • Added the Authorization Code authorization strategy for web clients.
  • Changed the production API root URL to https://api.ecobee.com. The previous URLs will still work until further notice, however the new root is preferred.
  • Fixed issue with GET Runtime Report returning sensor temperature values as Temperature F * 10, it now returns values as Degrees F. Updated documentation to explicitly indicate that Runtime Report returns temperatures in Degrees F in Core Concepts.
  • Fixed another issue with GET Runtime Report which was returning thermostat runtime data for the period specified in thermostat time rather than UTC as indicated by the documentation. The sensor and thermostat runtime data will now be for the same period as specified in UTC.
  • The way thermostat updates were handled has been made more explicit and less ambiguous. When updating a property which you could not update due to permissions, previous behaviour was to silently ignore that property. New behaviour is to return an error indicating which property you are forbidden to update.
  • Various documentation enhancements and clarifications.

April 2013

  • Documentation clarifications added to various parts of the documentation based on beta feedback.
  • Obsolete Settings object properties removed: statusIntervalSeconds, coldTempAlertNotify, hotTempAlertNotify
  • Responses will now use the application/json rather than the previous text/json content type. This makes it more browser friendly.
  • Added thermostat.runtime.runtimeRev property which contains the runtime revision value from thermostat summary.
  • Augmented the GET Runtime Report to optionally provide sensor historical data and include a start and end time intervals.
  • DemandResponse.type property has been removed as it is not used.
  • Event.fan default value will now be based off the current program climate and hvac mode of the thermostat. Previously defaulted to "on".
  • Added Meter Report for reporting on electricity meters.
  • Fixed an issue with alert date/times being represented in UTC time. They are not represented in thermostat time as per documentation.

January 2013