Learn how to create, list, get, update, and delete thermostat schedules for thermostats.
Once you have created a set of climate presets for a thermostat, you can define schedules using the /thermostats/schedules/create endpoint. The Seam API's scheduling mechanism is flexible and intelligent. It can prioritize and handle multiple scheduled climate presets. For example, you could set a fallback energy-saving climate preset for whenever a short-term rental property is unoccupied. Then, you could schedule—in advance—a "comfort" climate preset to correspond to each upcoming guest's stay.
Each thermostat schedule can contain the following properties:
Property
Description
name
(Optional) User-friendly name to identify the thermostat schedule.
climate_preset_key
(Required) Key of the climate preset to use for the thermostat schedule.
max_override_period_minutes
Number of minutes for which a person at the thermostat can change the thermostat's settings after the activation of the scheduled climate preset.
Default: 0
See also Specifying Manual Override Permissions.
starts_at
(Required) Date and time at which the thermostat schedule starts, in ISO 8601 format.
ends_at
(Required) Date and time at which the thermostat schedule ends, in ISO 8601 format.
Setting the Schedule
In the Seam API, use the starts_at and ends_at parameters to define the time period during which to apply an existing climate preset. For example, a short-term rental host could set starts_at to the beginning of a guest reservation or perhaps even slightly before the reservation starts so that the property reaches a comfortable temperature in time for guest arrival. The host could set ends_at to coincide with the end of the reservation.
starts_at is required and must be unique within all the schedules for the thermostat. However, if you want to schedule a climate preset that starts immediately, set start_at to a time in the past. Alternately, you can activate a climate preset immediately.
Specifying Manual Override Permissions
When creating a thermostat schedule for a thermostat, you can specify is_override_allowed and optionally the max_override_period_minutes. The is_override_allowed parameter indicates whether a person at the thermostat or via the Seam API can change the thermostat's settings for the active duration of that thermostat schedule. Setting max_override_period_minutes defines the length of the allowed override period. If an override period is allowed, at the end of this period, Seam sets the thermostat back to the climate preset defined by the thermostat schedule. The override period starts again each time a person makes a change at the thermostat or using the API.
Through these override period settings, the Seam API provides you with the flexibility to customize the thermostat behavior to suit your needs. For example, a multifamily property manager may want to give complete control of the thermostat to a unit's residents as soon as they move into the unit. However, a short-term rental host may want to enforce stricter rules to ensure that their guests are using the associated HVAC system in a reasonable manner.
To allow complete control at the thermostat, set is_override_allowed to true and max_override_period_minutes to null. To disable manual overrides entirely, set is_override_allowed to false.
Create a Thermostat Schedule
To create a thermostat schedule, issue a /thermostats/schedules/create request, providing the device_id of the desired thermostat, as well as the climate_preset_key, and the starts_at and ends_at timestamps. You can also specify a name for the thermostat schedule and the desired is_override_allowed and max_override_period_minutes values.
Suppose a short-term rental host wants to set a fallback "unoccupied" climate preset that takes effect immediately, as well as scheduling an "occupied" climate preset for two periods that correspond to guest reservations.
The following example shows how to set up these schedules:
Request:
# Get the thermostat.thermostat = seam.devices.get( device_id ="2d488679-6f07-4810-aed2-e726872c1dd5")# Set the fallback climate preset.seam.thermostats.set_fallback_climate_preset( device_id = thermostat.device_id, climate_preset_key ="unoccupied")# Create the thermostat schedule for the first reservation.seam.thermostats.schedules.create( device_id = thermostat.device_id, name ="Joe's stay", climate_preset_key ="occupied", starts_at ="2024-11-10T15:00:00Z", ends_at ="2024-11-15T12:00:00Z", is_override_allowed =True, max_override_period_minutes =90)# Create the thermostat schedule for the second reservation.seam.thermostats.schedules.create( device_id = thermostat.device_id, name ="Jane's stay", climate_preset_key ="occupied", starts_at ="2024-11-16T15:00:00Z", ends_at ="2024-11-18T12:00:00Z", is_override_allowed =True, max_override_period_minutes =90)
// Get the thermostat.constthermostat=awaitseam.devices.get({ device_id:"2d488679-6f07-4810-aed2-e726872c1dd5"});// Set the fallback climate preset.awaitseam.thermostats.setFallbackClimatePreset({ device_id:thermostat.device_id, climate_preset_key:"unoccupied"});// Create the thermostat schedule for the first reservation.awaitseam.thermostats.schedules.create({ device_id:thermostat.device_id, name:"Joe's stay", climate_preset_key:"occupied", starts_at:"2024-11-10T15:00:00Z", ends_at:"2024-11-15T12:00:00Z", is_override_allowed:true, max_override_period_minutes:90});// Create the thermostat schedule for the second reservation.awaitseam.thermostats.schedules.create({ device_id:thermostat.device_id, name:"Jane's stay", climate_preset_key:"occupied", starts_at:"2024-11-16T15:00:00Z", ends_at:"2024-11-18T12:00:00Z", is_override_allowed:true, max_override_period_minutes:90});
// Get the thermostat.$thermostat = $seam->devices->get( device_id:"2d488679-6f07-4810-aed2-e726872c1dd5");// Set the fallback climate preset.$seam->thermostats->set_fallback_climate_preset( device_id: $thermostat->device_id, climate_preset_key:"unoccupied");// Create the thermostat schedule for the first reservation.$seam->thermostats->schedules->create( device_id: $thermostat->device_id, name:"Joe's stay", climate_preset_key:"occupied", starts_at:"2024-11-10T15:00:00Z", ends_at:"2024-11-15T12:00:00Z", is_override_allowed:true, max_override_period_minutes:90);// Create the thermostat schedule for the second reservation.$seam->thermostats->schedules->create( device_id: $thermostat->device_id, name:"Jane's stay", climate_preset_key:"occupied", starts_at:"2024-11-16T15:00:00Z", ends_at:"2024-11-18T12:00:00Z", is_override_allowed:true, max_override_period_minutes:90);
To retrieve all thermostat schedules for a thermostat, issue a /thermostats/schedules/list request, specifying the device_id of the desired thermostat.
To get a specific thermostat schedule, issue a /thermostats/schedules/get request, including the thermostat_schedule_id of the desired thermostat schedule.
To update a thermostat schedule, issue a /thermostats/schedules/update request, providing the thermostat_schedule_id of the desired thermostat schedule and the desired updated settings.
To delete a thermostat schedule, issue a /thermostats/schedules/delete request, providing the thermostat_schedule_id of the desired thermostat schedule.
