Request and Response

The following provides some guidance and examples on making requests. It also covers the common response structure.

GET Requests

GET requests require the encoded JSON body of the request to be passed on the URL. The following is an example of a GET Thermostats request which will return all the thermostats registered to the user and any alerts they may have:

HEADERS:
	Content-Type: application/json;charset=UTF-8
	Authorization: Bearer Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg
	
REQUEST:
	GET https://api.ecobee.com/1/thermostat?format=json&body=%7B%22selection%22%3A%7B%22selectionType%22%3A%22registered%22%2C%22selectionMatch%22%3A%22%22%2C%22includeAlerts%22%3Atrue%7D%7D
                

The decoded body in this case is the following:

{"selection":{"selectionType":"registered","selectionMatch":"","includeAlerts":true}}

POST Requests

POST requests contain the JSON payload in the body content of the request. The following is an example of an update to a set of management thermostats in SetA which changes the minimum fan on-time to 30 minutes and puts the thermostat into a hold at 60 degrees (F) with a duration until the next program transition for each thermostat selected.

HEADERS:
	Content-Type: application/json;charset=UTF-8
	Authorization: Bearer Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg
	
REQUEST:
	POST https://api.ecobee.com/1/thermostat?format=json
	
POST BODY:
	%7B+%09%22selection%22%3A%7B+%09%09%22selectionType%22%3A%22managementSet%22%2C+%09%09%22selectionMatch%22%3A%22%2FSetA%22+%09%7D%2C+%09%22functions%22%3A%5B+%09%09%7B+%09%09%09%22type%22%3A%22setHold%22%2C+%09%09%09%22params%22%3A%7B+%09%09%09%09%22heatHoldTemp%22%3A600%2C+%09%09%09%09%22coolHoldTemp%22%3A600%2C+%09%09%09%09%22holdType%22%3A%22nextTransition%22+%09%09%09%7D+%09%09%7D+%09%5D+%7D+
                

The decoded body in this case is the following:

{
	"selection":{
		"selectionType":"managementSet",
		"selectionMatch":"/SetA"
	},
	"thermostat":{
		"settings":{
			"fanMinOnTime":30
		}	
	},
	"functions":[
		{
			"type":"setHold",
			"params":{
				"heatHoldTemp":600,
				"coolHoldTemp":600,
				"holdType":"nextTransition"
			}
		}
	]
}               
                

Responses

All ecobee API requests have a basic structured format. All responses will always contain the Status object in the response. An example of a response is below:

{
	"page": {								// The Page.
		"page": 1,
		"totalPages": 1,
		"pageSize": 1,
		"total": 1
	},
	"thermostatList": [		  				// The Response.
		{											
			"identifier": "161775386723",
			"name": "",
			"thermostatRev": "110128234025",
			"isRegistered": true,
			"modelNumber": "Smart",
			"serialNumber": "1",
			"productCode": "1",
			"lastModified": "2011-01-28 23:40:25",
			"alerts": [],
			"settings": {
			"hvacMode": "heat",
			"lastServiceDate": "2011-01-28",
			"serviceRemindMe": false,
			...snip...
		}
	],
	"status": {								// The Status.
		"code": 0,
		"message": ""
	}
}
				

The response above contains three main sections.

The Page

The Page object is optional and will only appear for responses which can be paged. It will not appear for responses which do not contain pageable content.

The Response

The Response object varies from call to call. The response may contain multiple properties on the root response object, or just one. The details of each response are contained within the individual request documentation.

The Status

The Status object contains the response code for the request. It will also contain an appropriate message when an error occurs. The status is always returned from all GET and POST calls. A non-zero code means that an error occurred. Refer to the Response Codes section for details of each error which may be returned.

Back To Top