Selection Object
The selection object defines the resources and information to return as part of a response. The selection is required in all requests however meaning of some selection fields is only meaningful to certain types of requests.
The selectionType parameter defines the type of selection to perform. The selectionMatch specifies the matching criteria for the type specified.
Utility Restrictions
Utilities are constrained by a restricted list of GET (or view) access to certain include* properties of the Thermostat object. This exists to protect the Thermostat owner's private information.
The list of include* properties the Utility can use for GET requests is:
- includeRuntime
- includeExtendedRuntime
- includeSettings
- includeLocation
- includeProgram
- includeEvents
- includeDevice
- includeTechnician
- includeUtility
- includeAlerts
- includeWeather
- includeOemConfig
- includeEquipmentStatus
- includeNotificationSettings
- includePrivacy
- includeVersion
- includeSecuritySettings
- includeSensors
| Selection Type | Account Type | Selection Match Example | Description |
|---|---|---|---|
| registered | Smart only. | match is not used. | When this is set the thermostats registered to the current user will be returned. This is only usable with Smart thermostats registered to a user. It does not work on EMS thermostats and may not be used by a Utility who is not the owner of thermostats. |
| thermostats | All accounts | identifier1,identifier2,etc.. | Select only those thermostats listed in the CSV match criteria. No spaces in the CSV string. There is a limit of 25 identifiers per request. |
| managementSet | EMS/Utility only. | /Toronto/Campus/BuildingA | Selects all thermostats for a given management set defined by the Management/Utility account. This is only available to Management/Utility accounts. "/" is the root, represented by the "My Sets" set. |
Properties
| Name | Type | Read Only | Required | Description |
|---|---|---|---|---|
| selectionType | Enum | no | yes | The type of match data supplied: Values: thermostats, registered, managementSet. |
| selectionMatch | String | no | yes | The match data based on selectionType (e.g. a list of thermostat identifiers in the case of a selectionType of thermostats) |
| includeRuntime | boolean | no | no | Include the thermostat runtime object. If not specified, defaults to false. |
| includeExtendedRuntime | boolean | no | no | Include the extended thermostat runtime object. If not specified, defaults to false. |
| includeSettings | boolean | no | no | Include the thermostat settings object. If not specified, defaults to false. |
| includeLocation | boolean | no | no | Include the thermostat location object. If not specified, defaults to false. |
| includeProgram | boolean | no | no | Include the thermostat program object. If not specified, defaults to false. |
| includeEvents | boolean | no | no | Include the thermostat calendar events objects. If not specified, defaults to false. |
| includeDevice | boolean | no | no | Include the thermostat device configuration objects. If not specified, defaults to false. |
| includeTechnician | boolean | no | no | Include the thermostat technician object. If not specified, defaults to false. |
| includeUtility | boolean | no | no | Include the thermostat utility company object. If not specified, defaults to false. |
| includeManagement | boolean | no | no | Include the thermostat management company object. If not specified, defaults to false. |
| includeAlerts | boolean | no | no | Include the thermostat's unacknowledged alert objects. If not specified, defaults to false. |
| includeReminders | boolean | no | no | |
| includeWeather | boolean | no | no | Include the current thermostat weather forecast object. If not specified, defaults to false. |
| includeHouseDetails | boolean | no | no | Include the current thermostat house details object. If not specified, defaults to false. |
| includeOemCfg | boolean | no | no | Include the current thermostat OemCfg object. If not specified, defaults to false. |
| includeEquipmentStatus | boolean | no | no | Include the current thermostat equipment status information. If not specified, defaults to false. |
| includeNotificationSettings | boolean | no | no | Include the current thermostat alert and reminders settings. If not specified, defaults to false. |
| includePrivacy | boolean | no | no | Include the current thermostat privacy settings. Note: access to this object is restricted to callers with implict authentication, setting this value to true without proper credentials will result in an authentication exception. |
| includeVersion | boolean | no | no | Include the current firmware version the Thermostat is running. If not specified, defaults to false. |
| includeSecuritySettings | boolean | no | no | Include the current securitySettings object for the selected Thermostat(s). If not specified, defaults to false. |
| includeSensors | boolean | no | no | Include the list of current thermostatRemoteSensor objects for the selected Thermostat(s). If not specified, defaults to false. |
| includeAudio | boolean | no | no | Include the audio configuration for the selected Thermostat(s). If not specified, defaults to false. |
| includeEnergy | boolean | no | no | Include the energy configuration for the selected Thermostat(s). If not specified, defaults to false. |
| includeCapabilities | boolean | no | no |