You can use the following Seam API "imperative" endpoints to set the current HVAC and fan mode settings for a connected thermostat, individually:
Note that it's important to check the capabilities of a thermostat before attempting to use an imperative endpoint. For example, if a thermostat is attached to an HVAC system that does not have cooling capabilities, you cannot use /thermostats/cool or /thermostats/heat_cool. To check the capabilities of a thermostat, retrieve the thermostat and confirm the .
These imperative operations return an that enables you to track the progress of the action. Poll this action attempt, until the action completes.
Further, Seam emits a when the thermostat reports a temperature within 1° Celsius of the heating or cooling temperature that you requested.
HVAC Settings
When you use an imperative endpoint to set the HVAC settings for a thermostat, you specify the and the desired in Fahrenheit or Celsius.
To set the HVAC mode and set points, issue a thermostat , , , or request and include the desired set points in the body of the request.
Fan Mode Settings
Seam supports the following fan mode settings:
Fan mode
Description
on
The fan runs all the time, regardless of whether the HVAC system is cooling or heating.
auto
The fan runs whenever the HVAC system is cooling or heating but does not run at other times.
circulate
The fan runs for a specific number of minutes each hour, regardless of whether the HVAC system is cooling or heating. This setting is only supported on certain Honeywell thermostats.
Process Overview
To configure and then verify a climate setting on a thermostat, perform the following steps:
Confirm the capabilities of the thermostat.
Execute the imperative climate setting request.
See the following instructions:
Device(
device_id='a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
can_hvac_heat=True, // You can use seam.thermostats.heat() on this device.
can_hvac_cool=True, // You can use seam.thermostats.cool() on this device.
can_hvac_heat_cool=True, // You can use seam.thermostats.heat_cool() on this device.
can_turn_off_hvac=True, // You can use seam.thermostats.off() on this device.
...
)
Request:
# Use GET or POST.
curl -X 'GET' \
'https://connect.getseam.com/devices/get' \
-H 'accept: application/json' \
-H "Authorization: Bearer ${SEAM_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
}'
Response:
{
"device": {
"device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
"can_hvac_heat": true, // You can use /thermostats/heat on this device.
"can_hvac_cool": true, // You can use /thermostats/cool on this device.
"can_hvac_heat_cool": true, // You can use /thermostats/heat_cool on this device.
"can_turn_off_hvac": true, // You can use /thermostats/off on this device.
...
},
"ok": true
}
{
device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
can_hvac_heat: true, // You can use seam.thermostats.heat() on this device.
can_hvac_cool: true, // You can use seam.thermostats.cool() on this device.
can_hvac_heat_cool: true, // You can use seam.thermostats.heatCool() on this device.
can_turn_off_hvac: true, // You can use seam.thermostats.off() on this device.
...
}
{
"device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
"can_hvac_heat": true, // You can use $seam->thermostats->heat() on this device.
"can_hvac_cool": true, // You can use $seam->thermostats->cool() on this device.
"can_hvac_heat_cool": true, // You can use $seam->thermostats->heat_cool() on this device.
"can_turn_off_hvac": true, // You can use $seam->thermostats->off() on this device.
...
}
Request:
// Coming soon!
Response:
// Coming soon!
Request:
// Coming soon!
Response:
// Coming soon!
Request:
// Coming soon!
Response:
// Coming soon!
Set a Thermostat to Heat Mode
Issue the thermostat heat request, providing the device_id of the thermostat and the heating_set_point_celsius or heating_set_point_fahrenheit.
Request:
# Get the thermostat.
thermostat = seam.devices.get(
device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
)
# Confirm that the thermostat supports heat mode.
if thermostat.can_hvac_heat:
# Perform the heat request.
seam.thermostats.heat(
device_id = thermostat.device_id,
heating_set_point_celsius = 20
)
// Get the thermostat.
thermostat = seam.devices.get({
device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
});
# Confirm that the thermostat supports heat mode.
if (thermostat.can_hvac_heat)
# Perform the heat request.
seam.thermostats.heat(
device_id: thermostat.device_id,
heating_set_point_celsius: 20
)
end
// Get the thermostat.
thermostat = seam.devices.get({
device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
});
# Confirm that the thermostat supports cool mode.
if (thermostat.can_hvac_cool)
# Perform the cool request.
seam.thermostats.cool(
device_id: thermostat.device_id,
cooling_set_point_celsius: 25
)
end
// Get the thermostat.
thermostat = seam.devices.get({
device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
});
# Confirm that the thermostat supports heat-cool mode.
if (thermostat.can_hvac_heat_cool)
# Perform the heat_cool request.
seam.thermostats.heat_cool(
device_id: thermostat.device_id,
heating_set_point_celsius: 20,
cooling_set_point_celsius: 25
)
end
Issue the thermostat off request, providing the device_id of the thermostat.
Request:
# Get the thermostat.
thermostat = seam.devices.get(
device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
)
# Confirm that the thermostat supports off mode.
if thermostat.can_turn_off_hvac:
# Perform the off request.
seam.thermostats.off(
device_id = thermostat.device_id
)
// Get the thermostat.
const thermostat = await seam.devices.get({
device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
});
// Confirm that the thermostat supports off mode.
if (thermostat.can_turn_off_hvac) {
// Perform the off request.
await seam.thermostats.off({
device_id: thermostat.device_id
})
};
// Get the thermostat.
thermostat = seam.devices.get({
device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
});
# Confirm that the thermostat supports off mode.
if (thermostat.can_turn_off_hvac)
# Perform the off request.
seam.thermostats.off(
device_id: thermostat.device_id
)
end
// Get the thermostat.
$thermostat = $seam->devices->get(
device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
);
// Confirm that the thermostat supports off mode.
if ($thermostat->can_turn_off_hvac) {
// Perform the off request.
$seam->thermostats->off(
device_id: $thermostat->device_id
);
}
If desired, configure a webhook to watch for a thermostat.temperature_reached_set_point event that indicates that the thermostat has reported a temperature within 1° Celsius of the heating or cooling that you requested.
See .
Before you attempt to set the HVAC or fan mode settings for a thermostat, be sure to confirm that your device has the capability to perform these operations. You can inspect the capabilities of a device by checking the following for the device:
Use the endpoint for a specific device to return these capability flags. Then, use an if statement or similar check to confirm that the relevant flag is both present and true before attempting to perform the imperative thermostat action.
If the relevant capability flag is false or not present, you can view the of the device, or for the device, and related to the device to learn more about the cause of these issues. For example, you could examine device.properties.online. In addition, you could look for a device.disconnected event.
You can and specify a desired heating temperature. By establishing the set point, the thermostat activates the associated heating system to maintain the specified temperature.
You can and specify a desired cooling temperature. By establishing the set point, the thermostat activates the associated cooling system to maintain the specified temperature.
You can and specify desired temperatures for both heating and cooling. By establishing the set points, the thermostat activates the associated heating and cooling systems as needed to maintain the specified temperature range.
You can , which deactivates the associated heating and cooling systems. In this state, the thermostat does not regulate indoor temperatures.
You can . For details about the supported fan modes, see .
The imperative HVAC or fan mode setting request returns an . Use the action_attempt_id from this response to poll the associated action attempt using the request. When the setting modification completes successfully, the status of the action attempt changes to success.
