> ## Documentation Index
> Fetch the complete documentation index at: https://www.seam.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with Tado Thermostats

> Connect Tado thermostats to Seam, check each room's supported HVAC modes, set the temperature, and schedule climate presets.

Use Seam to connect a Tado account, list its rooms as thermostats, set a room's HVAC mode and set point, and schedule climate presets. Tado supports `heat`, `cool`, and `off` only, and each room reports its own capabilities. Check the [Tado-specific restrictions](https://www.seam.co/docs/device-and-system-integration-guides/tado-thermostats/index.md#brand-specific-restrictions) before you build.

For real thermostats, complete the [Tado setup guide](https://www.seam.co/docs/device-and-system-integration-guides/tado-thermostats/tado-setup-guide.md) first. [Create a Seam account and get an API key](https://console.seam.co/) to try [virtual Tado thermostats](https://www.seam.co/docs/device-and-system-integration-guides/tado-thermostats/sandbox-tado-thermostats.md) in a sandbox workspace.

## Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an [OpenAPI](https://connect.getseam.com/openapi.json) spec.

* JavaScript / TypeScript ([npm](https://www.npmjs.com/package/seam), [GitHub](https://github.com/seamapi/javascript))
* Python ([pip](https://pypi.org/project/seam/), [GitHub](https://github.com/seamapi/python))
* Ruby Gem ([rubygem](https://rubygems.org/gems/seam), [GitHub](https://github.com/seamapi/ruby))
* PHP ([packagist](https://packagist.org/packages/seamapi/seam), [GitHub](https://github.com/seamapi/php))
* C# ([nuget](https://www.nuget.org/packages/Seam), [GitHub](https://github.com/seamapi/csharp))
* Go ([GitHub](https://github.com/seamapi/go))

First, install a Seam SDK, as follows:

> [tab] JavaScript
>
> ```bash theme={"dark"}
> npm i seam
> ```

> [tab] Python
>
> ```bash theme={"dark"}
> pip install seam
> # For some development environments, use pip3 in this command instead of pip.
> ```

> [tab] Ruby
>
> ```bash theme={"dark"}
> bundle add seam
> ```

> [tab] PHP
>
> ```bash theme={"dark"}
> composer require seamapi/seam
> ```

> [tab] C#
>
> Install using [nuget](https://www.nuget.org/packages/Seam).

> [tab] Go
>
> ```bash theme={"dark"}
> go get github.com/seamapi/go
> ```

The Java examples in this guide use the HTTP client built into Java 11 and later, so they need no extra package.

Next, go to [https://console.seam.co/](https://console.seam.co/) and [sign up for Seam](https://www.seam.co/docs/core-concepts/seam-console.md#create-a-seam-account) to get your [API key](https://www.seam.co/docs/core-concepts/authentication/api-keys.md).

Then, export your API key as an environment variable.

```bash theme={"dark"}
$ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
```

> [!NOTE]
>
> This guide uses a [sandbox
> workspace](https://www.seam.co/docs/core-concepts/workspaces.md#sandbox-workspaces). You can only connect
> virtual devices and systems in this type of workspace. If you want to connect
> a real Tado thermostat, use a [non-sandbox
> workspace](https://www.seam.co/docs/core-concepts/workspaces.md#production-workspaces) and API key.

***

## Step 2: Link your Tado account with Seam

To control your Tado thermostats using the Seam API, you must first authorize your Seam workspace to connect to your Tado account. If your application needs to connect to your users' Tado accounts, Seam provides fully-embedded, [customizable](https://www.seam.co/docs/core-concepts/connect-webviews/customizing-connect-webviews.md) client-side [Connect Webviews](https://www.seam.co/docs/core-concepts/connect-webviews.md) to collect their authorization securely.

Tado doesn't let other apps collect a Tado password. Instead, the Connect Webview shows a link and a short code. Your user opens the link, signs in to Tado on Tado's own site, and approves Seam there. The Connect Webview then finishes on its own.

> [!TIP]
>
> This guide shows you how to create a Connect Webview programmatically using the Seam API.
>
> The [Seam Console](https://www.seam.co/docs/core-concepts/seam-console.md) provides another easy way to connect devices to your Seam workspace.
>
> Go to [https://console.seam.co/](https://console.seam.co/). On the **Devices** page, click **+ Add Devices**. Then, see [Authorize your workspace](#authorize-your-workspace) in this guide to complete the Connect Webview authorization flow.

### Create a Connect Webview

Create a `connect_webview` object and then note the returned URL.

The C#, Java, and Go examples in this guide send requests to the Seam API directly. The Java and Go examples define a small `seamPost` helper here, and later steps reuse it.

**Code:**

```javascript JavaScript theme={"dark"}
import { Seam } from 'seam'

const seam = new Seam() // Seam automatically uses your exported SEAM_API_KEY.

const connectWebview = await seam.connectWebviews.create({
  accepted_providers: ['tado'],
})

console.log(connectWebview.login_successful) // false

// Use the returned Connect Webview URL to display
// the Connect Webview authorization flow to your user.
console.log(connectWebview.url)
```

```bash cURL theme={"dark"}
curl -X 'POST' \
  'https://connect.getseam.com/connect_webviews/create' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "accepted_providers": ["tado"]
}' | jq -r '"Login Successful (false): " + (.connect_webview.login_successful | tostring),
  "URL: " + .connect_webview.url'
  # Use the returned Connect Webview URL to display
  # the Connect Webview authorization flow to your user.
```

```python Python theme={"dark"}
from seam import Seam

seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.

connect_webview = seam.connect_webviews.create(accepted_providers=["tado"])

assert connect_webview.login_successful is False

# Use the returned Connect Webview URL to display
# the Connect Webview authorization flow to your user.
print(connect_webview.url)
```

```ruby Ruby theme={"dark"}
require "seam"

seam = Seam.new() # Seam automatically uses your exported SEAM_API_KEY.

connect_webview = seam.connect_webviews.create(accepted_providers: ["tado"])

puts connect_webview.login_successful # false

# Use the returned Connect Webview URL to display
# the Connect Webview authorization flow to your user.
puts connect_webview.url
```

```php PHP theme={"dark"}
<?php
require 'vendor/autoload.php';

$seam = new Seam\SeamClient(); // Seam automatically uses your exported SEAM_API_KEY.

$connect_webview = $seam->connect_webviews->create(
    accepted_providers: ["tado"]
);

echo $connect_webview->login_successful ? 'true' : 'false', "\n"; // false

// Use the returned Connect Webview URL to display
// the Connect Webview authorization flow to your user.
echo $connect_webview->url;
```

```csharp C# theme={"dark"}
using System;
using Seam.Client;
using Newtonsoft.Json.Linq;

var seam = new SeamClient(Environment.GetEnvironmentVariable("SEAM_API_KEY"));

var connectWebviewResponse = await seam.PostAsync<JObject>(
    "/connect_webviews/create",
    new RequestOptions {
        Data = new { accepted_providers = new[] { "tado" } }
    }
);
var connectWebview = connectWebviewResponse.EnsureData("/connect_webviews/create")["connect_webview"]!;

Console.WriteLine((bool)connectWebview["login_successful"]!); // False

// Use the returned Connect Webview URL to display
// the Connect Webview authorization flow to your user.
Console.WriteLine((string)connectWebview["url"]!);
```

```java Java theme={"dark"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

// Java 11+ HTTP helper. Later steps reuse seamPost.
static final HttpClient client = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(30))
    .build();

static String seamPost(String path, String jsonBody)
    throws java.io.IOException, InterruptedException {
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://connect.getseam.com" + path))
      .timeout(Duration.ofSeconds(30))
      .header("Authorization", "Bearer " + System.getenv("SEAM_API_KEY"))
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
      .build();
  HttpResponse<String> response =
      client.send(request, HttpResponse.BodyHandlers.ofString());
  if (response.statusCode() < 200 || response.statusCode() >= 300) {
    throw new IllegalStateException(response.body());
  }
  return response.body();
}

// The response JSON contains connect_webview.url and
// connect_webview.login_successful (false). Use the URL to display
// the Connect Webview authorization flow to your user.
System.out.println(
    seamPost("/connect_webviews/create", "{\"accepted_providers\":[\"tado\"]}")
);
```

```go Go theme={"dark"}
import (
    "context"
    "fmt"
    "net/http"
    "os"
    "time"

    "github.com/seamapi/go/core"
)

// seamPost sends a request to the Seam API. Later steps reuse it.
func seamPost(path string, request any) map[string]any {
    caller := core.NewCaller(&core.CallerParams{
        Client: &http.Client{Timeout: 30 * time.Second},
        MaxAttempts: 1,
    })
    var response map[string]any
    err := caller.Call(context.Background(), &core.CallParams{
        URL: "https://connect.getseam.com" + path,
        Method: http.MethodPost,
        Headers: http.Header{
            "Authorization": []string{"Bearer " + os.Getenv("SEAM_API_KEY")},
        },
        Request: request,
        Response: &response,
    })
    if err != nil {
        panic(err)
    }
    return response
}

connectWebview := seamPost("/connect_webviews/create", map[string]any{
    "accepted_providers": []string{"tado"},
})["connect_webview"].(map[string]any)

fmt.Println(connectWebview["login_successful"]) // false

// Use the returned Connect Webview URL to display
// the Connect Webview authorization flow to your user.
fmt.Println(connectWebview["url"])
```

```bash Seam CLI theme={"dark"}
seam connect-webviews create --accepted_providers ["tado"]
```

**Output:**

```json theme={"dark"}
{
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "login_successful": false,
  "url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=12345678-1234-1234-1234-123456789012&auth_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  ...
}
```

***

### Authorize Your Workspace

In a web browser, go to the URL that the Connect Webview object returned.

For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt [Connect Account Button](https://www.seam.co/docs/ui-components/overview/react-components/connect-account-button.md) within our suite of [Seam Components](https://www.seam.co/docs/ui-components/overview.md) that help you build your device management flow.

> [!TIP]
>
> Because you're using a sandbox workspace, you connect Seam's test Tado
> account. We provide [virtual devices](https://www.seam.co/docs/device-and-system-integration-guides/tado-thermostats/sandbox-tado-thermostats.md) for each of
> the brands that we support. These sandbox devices and systems enable you to
> test your app with devices from multiple brands without the need to own all
> the corresponding physical devices.

Complete the Connect Webview authorization flow, as follows:

1. In the Connect Webview, select **Open tado**. In a sandbox workspace, this link opens a sandbox approval page, which connects the [Tado sandbox account](https://www.seam.co/docs/device-and-system-integration-guides/tado-thermostats/sandbox-tado-thermostats.md) right away. You don't need to sign in.
2. Return to the Connect Webview. It continues on its own within a few seconds. You can also select **I've approved Seam in tado**.

Confirm that authorization through the Connect Webview was successful by querying its status.

**Code:**

```javascript JavaScript theme={"dark"}
const updatedConnectWebview = await seam.connectWebviews.get({
  connect_webview_id: connectWebview.connect_webview_id,
})

console.log(updatedConnectWebview.login_successful) // true
```

```bash cURL theme={"dark"}
curl -X 'POST' \
  'https://connect.getseam.com/connect_webviews/get' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
  \"connect_webview_id\": \"${connect_webview_id}\"
}" | jq -r '"Login Successful (true): " + (.connect_webview.login_successful | tostring)'
```

```python Python theme={"dark"}
updated_connect_webview = seam.connect_webviews.get(
    connect_webview_id=connect_webview.connect_webview_id
)

assert updated_connect_webview.login_successful is True
```

```ruby Ruby theme={"dark"}
updated_connect_webview = seam.connect_webviews.get(
  connect_webview_id: connect_webview.connect_webview_id
)

puts updated_connect_webview.login_successful # true
```

```php PHP theme={"dark"}
$updated_connect_webview = $seam->connect_webviews->get(
    connect_webview_id: $connect_webview->connect_webview_id
);

echo $updated_connect_webview->login_successful ? 'true' : 'false', "\n"; // true
```

```csharp C# theme={"dark"}
var updatedConnectWebviewResponse = await seam.PostAsync<JObject>(
    "/connect_webviews/get",
    new RequestOptions {
        Data = new { connect_webview_id = (string)connectWebview["connect_webview_id"]! }
    }
);
var updatedConnectWebview = updatedConnectWebviewResponse.EnsureData("/connect_webviews/get")["connect_webview"]!;

Console.WriteLine((bool)updatedConnectWebview["login_successful"]!); // True
```

```java Java theme={"dark"}
// Uses the seamPost helper from the previous example.
// Check connect_webview.login_successful (true) in the response JSON.
System.out.println(seamPost(
    "/connect_webviews/get",
    "{\"connect_webview_id\":\"12345678-1234-1234-1234-123456789012\"}"
));
```

```go Go theme={"dark"}
// Uses the seamPost helper from the previous example.
updatedConnectWebview := seamPost("/connect_webviews/get", map[string]any{
    "connect_webview_id": connectWebview["connect_webview_id"],
})["connect_webview"].(map[string]any)

fmt.Println(updatedConnectWebview["login_successful"]) // true
```

```bash Seam CLI theme={"dark"}
seam connect-webviews get --connect_webview_id "12345678-1234-1234-1234-123456789012"
```

**Output:**

```json theme={"dark"}
{
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "login_successful": true,
  ...
}
```

***

## Step 3: Retrieve Tado thermostat devices

When you link a Tado account with Seam, we create a `device` object for each heating room and each Smart AC Control room in the account. Hot water rooms don't appear. You can retrieve these devices using the [List Devices](https://www.seam.co/docs/api/devices/list.md) and [Get Device](https://www.seam.co/docs/api/devices/get.md) endpoints.

The device's `device_type` is `tado_thermostat`, and `properties.tado_metadata` identifies the Tado home and room. The device also reports the room's temperature and humidity, its current climate setting, its supported HVAC modes, and its set point range.

**Code:**

```javascript JavaScript theme={"dark"}
// Retrieve all devices, filtered by manufacturer,
// which is one of several filters that list() supports.
const allTadoThermostats = await seam.devices.list({ manufacturer: 'tado' })

// Select the Living Room heating room as an example.
const livingRoom = allTadoThermostats.find(
  (device) => device.properties.tado_metadata?.zone_name === 'Living Room',
)

// Inspect specific properties.
console.log('Current temperature: ' + livingRoom.properties.temperature_celsius)
console.log(
  'HVAC modes: ' + livingRoom.properties.available_hvac_mode_settings,
)

// View the entire returned device object.
console.log(livingRoom)
```

```bash cURL theme={"dark"}
# Retrieve all devices, filtered by manufacturer, which is
# one of several filters that the list endpoint supports.
all_tado_thermostats=$(
  curl -X 'POST' \
    'https://connect.getseam.com/devices/list' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
    "manufacturer": "tado"
  }')

# Select the Living Room heating room as an example.
living_room=$(jq -r '.devices[] | select(.properties.tado_metadata.zone_name == "Living Room")' <<< ${all_tado_thermostats})

# Inspect specific properties.
echo $(jq -r '"Current temperature: " + (.properties.temperature_celsius | tostring)' <<< ${living_room})
echo $(jq -r '"HVAC modes: " + (.properties.available_hvac_mode_settings | join(","))' <<< ${living_room})

# View the entire returned device object.
echo ${living_room}
```

```python Python theme={"dark"}
from pprint import pprint

# Retrieve all devices, filtered by manufacturer,
# which is one of several filters that list() supports.
all_tado_thermostats = seam.devices.list(manufacturer="tado")

# Select the Living Room heating room as an example.
living_room = next(
    device
    for device in all_tado_thermostats
    if device.properties["tado_metadata"]["zone_name"] == "Living Room"
)

# Inspect specific properties.
pprint("Current temperature: " + str(living_room.properties["temperature_celsius"]))
pprint("HVAC modes: " + str(living_room.properties["available_hvac_mode_settings"]))

# View the entire returned device object.
pprint(living_room)
```

```ruby Ruby theme={"dark"}
# Retrieve all devices, filtered by manufacturer,
# which is one of several filters that list() supports.
all_tado_thermostats = seam.devices.list(manufacturer: "tado")

# Select the Living Room heating room as an example.
living_room = all_tado_thermostats.find do |device|
  device.properties.tado_metadata.zone_name == "Living Room"
end

# Inspect specific properties.
puts "Current temperature: " + living_room.properties.temperature_celsius.to_s
puts "HVAC modes: " + living_room.properties.available_hvac_mode_settings.join(",")

# View the entire returned device object.
puts living_room.inspect
```

```php PHP theme={"dark"}
// Retrieve all devices, filtered by manufacturer,
// which is one of several filters that list() supports.
$all_tado_thermostats = $seam->devices->list(manufacturer: "tado");

// Select the Living Room heating room as an example.
$living_room = null;
foreach ($all_tado_thermostats as $device) {
    if ($device->properties->tado_metadata->zone_name === "Living Room") {
        $living_room = $device;
        break;
    }
}

// Inspect specific properties.
echo "Current temperature: ", $living_room->properties->temperature_celsius, "\n";
echo "HVAC modes: ", implode(",", $living_room->properties->available_hvac_mode_settings), "\n";

// View the entire returned device object.
echo json_encode($living_room, JSON_PRETTY_PRINT);
```

```csharp C# theme={"dark"}
using System.Linq;

var devicesResponse = await seam.PostAsync<JObject>(
    "/devices/list",
    new RequestOptions { Data = new { manufacturer = "tado" } }
);
var allTadoThermostats = (JArray)devicesResponse.EnsureData("/devices/list")["devices"]!;

// Select the Living Room heating room as an example.
var livingRoom = allTadoThermostats.First(
    device => (string?)device["properties"]?["tado_metadata"]?["zone_name"] == "Living Room"
);

// Inspect specific properties.
Console.WriteLine("Current temperature: " + livingRoom["properties"]!["temperature_celsius"]);
Console.WriteLine("HVAC modes: " + string.Join(",", livingRoom["properties"]!["available_hvac_mode_settings"]!));

// View the entire returned device object.
Console.WriteLine(livingRoom);
```

```java Java theme={"dark"}
// Uses the seamPost helper from Step 2.
// Find the device whose properties.tado_metadata.zone_name is "Living Room"
// in the response JSON, and note its device_id.
System.out.println(seamPost("/devices/list", "{\"manufacturer\":\"tado\"}"));
```

```go Go theme={"dark"}
// Uses the seamPost helper from Step 2.
devices := seamPost("/devices/list", map[string]any{
    "manufacturer": "tado",
})["devices"].([]any)

// Select the Living Room heating room as an example.
var livingRoom map[string]any
for _, item := range devices {
    device := item.(map[string]any)
    properties := device["properties"].(map[string]any)
    metadata := properties["tado_metadata"].(map[string]any)
    if metadata["zone_name"] == "Living Room" {
        livingRoom = device
    }
}

// Inspect specific properties.
properties := livingRoom["properties"].(map[string]any)
fmt.Println("Current temperature:", properties["temperature_celsius"])
fmt.Println("HVAC modes:", properties["available_hvac_mode_settings"])
```

```bash Seam CLI theme={"dark"}
seam devices list --manufacturer "tado"
```

**Output:**

```json theme={"dark"}
Current temperature: 12.16
HVAC modes: heat,off
{
  "device_id": "11111111-1111-1111-2222-444444444444",
  "device_type": "tado_thermostat",
  "display_name": "Living Room",
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "connected_account_id": "11111111-1111-1111-1111-222222222222",
  "properties": {
    "manufacturer": "tado",
    "online": true,
    "name": "Living Room",
    "temperature_celsius": 12.16,
    "relative_humidity": 0.463,
    "available_hvac_mode_settings": ["heat", "off"],
    "available_fan_mode_settings": [],
    "min_heating_set_point_celsius": 5,
    "max_heating_set_point_celsius": 25,
    "current_climate_setting": {
      "hvac_mode_setting": "heat",
      "heating_set_point_celsius": 18,
      ...
    },
    "tado_metadata": {
      "home_id": "1",
      "home_name": "Home",
      "zone_id": "1",
      "zone_name": "Living Room",
      "zone_type": "HEATING",
      "device_type": "RU02",
      "serial_no": "RU0000000001",
      "device_serial_numbers": ["RU0000000001", "VA0000000001"],
      ...
    },
    ...
  },
  "can_hvac_heat": true,
  "can_hvac_cool": false,
  "can_turn_off_hvac": true,
  ...
}
```

***

## Step 4: Control your Tado thermostat

Each device that you connect to Seam has a specific set of capabilities. [Capability flags](https://www.seam.co/docs/capability-guides/device-and-system-capabilities.md#capability-flags) tell your application what each device supports. For Tado, check `can_hvac_heat` and `can_hvac_cool` before you send a command: a heating room supports `heat` and `off`, and a Smart AC Control room supports `cool`, `off`, and usually `heat`.

Try out the following actions on your Tado thermostat:

* [Set the HVAC mode](#set-the-hvac-mode)
* [Verify the change](#verify-the-change)
* [Create and schedule climate presets](#create-and-schedule-climate-presets)

### Set the HVAC mode

To set the HVAC mode, use any of the following endpoints or their equivalents in the Seam SDKs:

* `/thermostats/heat`
* `/thermostats/cool`
* `/thermostats/off`
* `/thermostats/set_hvac_mode`

Specify the thermostat that you want to control by including the `device_id` in the request body. Also, include the desired temperature [set point](https://www.seam.co/docs/capability-guides/thermostats/understanding-thermostat-concepts/set-points.md). The set point must be within the room's range, such as `min_heating_set_point_celsius` and `max_heating_set_point_celsius`.

In this example, set the Living Room to `heat` with a heating set point of 21 °C. Each of these HVAC mode endpoints returns an [action attempt](https://www.seam.co/docs/core-concepts/action-attempts.md) to track the progress of the operation.

**Code:**

```javascript JavaScript theme={"dark"}
// Confirm that the device supports heat mode.
// You're using a capability flag here!
if (livingRoom.can_hvac_heat) {
  // Perform the heat operation and wait for the action attempt.
  const actionAttempt = await seam.thermostats.heat({
    device_id: livingRoom.device_id,
    heating_set_point_celsius: 21,
  })

  console.log(actionAttempt)
}
```

```bash cURL theme={"dark"}
# Confirm that the device supports heat mode.
# You're using a capability flag here!
if  $(jq -r '.can_hvac_heat' <<< ${living_room}); then \
  # Perform the heat operation and return an action attempt.
  curl -X 'POST' \
    'https://connect.getseam.com/thermostats/heat' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device_id' <<< ${living_room})\",
      \"heating_set_point_celsius\": 21
  }";
fi
```

```python Python theme={"dark"}
# Confirm that the device supports heat mode.
# You're using a capability flag here!
if living_room.can_hvac_heat:
    # Perform the heat operation and wait for the action attempt.
    action_attempt = seam.thermostats.heat(
        device_id=living_room.device_id, heating_set_point_celsius=21
    )

    pprint(action_attempt)
```

```ruby Ruby theme={"dark"}
# Confirm that the device supports heat mode.
# You're using a capability flag here!
if living_room.can_hvac_heat
  # Perform the heat operation and wait for the action attempt.
  action_attempt = seam.thermostats.heat(
    device_id: living_room.device_id,
    heating_set_point_celsius: 21,
  )

  puts action_attempt.inspect
end
```

```php PHP theme={"dark"}
// Confirm that the device supports heat mode.
// You're using a capability flag here!
if ($living_room->can_hvac_heat) {
    // Perform the heat operation and wait for the action attempt.
    $action_attempt = $seam->thermostats->heat(
        device_id: $living_room->device_id,
        heating_set_point_celsius: 21,
    );

    echo json_encode($action_attempt, JSON_PRETTY_PRINT);
}
```

```csharp C# theme={"dark"}
// Confirm that the device supports heat mode.
// You're using a capability flag here!
if ((bool?)livingRoom["can_hvac_heat"] == true) {
    // Perform the heat operation and return an action attempt.
    var heatResponse = await seam.PostAsync<JObject>(
        "/thermostats/heat",
        new RequestOptions {
            Data = new {
                device_id = (string)livingRoom["device_id"]!,
                heating_set_point_celsius = 21
            }
        }
    );

    Console.WriteLine(heatResponse.EnsureData("/thermostats/heat")["action_attempt"]);
}
```

```java Java theme={"dark"}
// Uses the seamPost helper from Step 2.
// Check that the device's can_hvac_heat is true before you send this request.
// The response JSON contains an action_attempt.
System.out.println(seamPost(
    "/thermostats/heat",
    "{\"device_id\":\"11111111-1111-1111-2222-444444444444\","
        + "\"heating_set_point_celsius\":21}"
));
```

```go Go theme={"dark"}
// Uses the seamPost helper from Step 2.
// Confirm that the device supports heat mode.
// You're using a capability flag here!
if livingRoom["can_hvac_heat"] == true {
    // Perform the heat operation and return an action attempt.
    actionAttempt := seamPost("/thermostats/heat", map[string]any{
        "device_id": livingRoom["device_id"],
        "heating_set_point_celsius": 21,
    })["action_attempt"]

    fmt.Println(actionAttempt)
}
```

```bash Seam CLI theme={"dark"}
seam thermostats heat --device_id "11111111-1111-1111-2222-444444444444" --heating_set_point_celsius 21
```

**Output:**

```json theme={"dark"}
{
  "action_attempt_id": "11111111-2222-3333-4444-555555555555",
  "action_type": "SET_HVAC_MODE",
  "status": "success",
  "result": {},
  "error": null
}
```

The JavaScript, Python, Ruby, and PHP SDKs wait for the action attempt to finish. The C#, Java, Go, cURL, and Seam CLI examples return the action attempt right away, with `status` set to `pending`. To follow it, poll [Get Action Attempt](https://www.seam.co/docs/api/action_attempts/get.md) until its `status` is `success` or `error`.

### Verify the change

Confirm that the action attempt succeeded, then get the device and read `properties.current_climate_setting`. Its `hvac_mode_setting` and `heating_set_point_celsius` show what Tado reports for the room. `properties.temperature_celsius` is the room's measured temperature, not the set point.

**Code:**

```javascript JavaScript theme={"dark"}
// Get the device by ID.
const updatedLivingRoom = await seam.devices.get({
  device_id: livingRoom.device_id,
})

// Inspect properties.current_climate_setting
// to confirm that the room is heating to 21 °C.
console.log(updatedLivingRoom.properties.current_climate_setting)
```

```bash cURL theme={"dark"}
# Get the device by ID.
updated_living_room=$(
  curl -X 'POST' \
    'https://connect.getseam.com/devices/get' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${SEAM_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
    \"device_id\": \"$(jq -r '.device_id' <<< ${living_room})\"
  }")

# Inspect properties.current_climate_setting
# to confirm that the room is heating to 21 °C.
echo $(jq -r '.device.properties.current_climate_setting' <<< ${updated_living_room})
```

```python Python theme={"dark"}
# Get the device by ID.
updated_living_room = seam.devices.get(device_id=living_room.device_id)

# Inspect properties.current_climate_setting
# to confirm that the room is heating to 21 °C.
pprint(updated_living_room.properties["current_climate_setting"])
```

```ruby Ruby theme={"dark"}
# Get the device by ID.
updated_living_room = seam.devices.get(device_id: living_room.device_id)

# Inspect properties.current_climate_setting
# to confirm that the room is heating to 21 °C.
puts updated_living_room.properties.current_climate_setting.inspect
```

```php PHP theme={"dark"}
// Get the device by ID.
$updated_living_room = $seam->devices->get(device_id: $living_room->device_id);

// Inspect properties.current_climate_setting
// to confirm that the room is heating to 21 °C.
echo json_encode($updated_living_room->properties->current_climate_setting, JSON_PRETTY_PRINT);
```

```csharp C# theme={"dark"}
// Get the device by ID.
var updatedLivingRoomResponse = await seam.PostAsync<JObject>(
    "/devices/get",
    new RequestOptions { Data = new { device_id = (string)livingRoom["device_id"]! } }
);
var updatedLivingRoom = updatedLivingRoomResponse.EnsureData("/devices/get")["device"]!;

// Inspect properties.current_climate_setting
// to confirm that the room is heating to 21 °C.
Console.WriteLine(updatedLivingRoom["properties"]!["current_climate_setting"]);
```

```java Java theme={"dark"}
// Uses the seamPost helper from Step 2.
// Check device.properties.current_climate_setting in the response JSON
// to confirm that the room is heating to 21 °C.
System.out.println(seamPost(
    "/devices/get",
    "{\"device_id\":\"11111111-1111-1111-2222-444444444444\"}"
));
```

```go Go theme={"dark"}
// Uses the seamPost helper from Step 2.
// Get the device by ID.
updatedLivingRoom := seamPost("/devices/get", map[string]any{
    "device_id": livingRoom["device_id"],
})["device"].(map[string]any)

// Inspect properties.current_climate_setting
// to confirm that the room is heating to 21 °C.
fmt.Println(updatedLivingRoom["properties"].(map[string]any)["current_climate_setting"])
```

```bash Seam CLI theme={"dark"}
seam devices get --device_id "11111111-1111-1111-2222-444444444444"
```

**Output:**

```json theme={"dark"}
{
  "hvac_mode_setting": "heat",
  "heating_set_point_celsius": 21,
  ...
}
```

If the reported settings don't match yet, Seam may not have read the room since the change. Get the device again after a short wait, or listen for thermostat [events](https://www.seam.co/docs/api/thermostats/events.md) instead of retrying the command. A failed command can also mean that the Tado account has used up its daily API allowance. For details, see [Sync Frequency and API Limits](https://www.seam.co/docs/device-and-system-integration-guides/tado-thermostats/index.md#sync-frequency-and-api-limits).

If you test a real thermostat, record its original mode and set point and restore them after the test. The setting you apply through Seam stays in place until the next change, and the room's own Tado schedule doesn't take over again on its own.

### Create and schedule climate presets

You can use the Seam API to create climate presets for Tado thermostats. Each climate preset is a saved group of settings, such as the HVAC mode and set point. For example, you could create a comfort preset for when a vacation rental is occupied and an eco preset for when it's empty.

You can schedule climate presets to start and stop whenever you'd like, and set a fallback climate preset that applies outside your schedules. Because Tado doesn't support fan modes, leave out `fan_mode_setting` when you create a Tado climate preset.

In this example, create comfort and eco presets for the Living Room, set eco as the fallback, and schedule the comfort preset for a guest's stay.

**Code:**

```javascript JavaScript theme={"dark"}
// Create the climate presets.
await seam.thermostats.createClimatePreset({
  device_id: livingRoom.device_id,
  climate_preset_key: 'comfort',
  name: 'Comfort',
  hvac_mode_setting: 'heat',
  heating_set_point_celsius: 21,
})

await seam.thermostats.createClimatePreset({
  device_id: livingRoom.device_id,
  climate_preset_key: 'eco',
  name: 'Eco',
  hvac_mode_setting: 'heat',
  heating_set_point_celsius: 16,
})

// Set eco as the fallback climate preset.
await seam.thermostats.setFallbackClimatePreset({
  device_id: livingRoom.device_id,
  climate_preset_key: 'eco',
})

// Schedule the comfort preset for a guest's stay.
await seam.thermostats.schedules.create({
  device_id: livingRoom.device_id,
  name: "Jane's stay",
  climate_preset_key: 'comfort',
  starts_at: '2026-12-18T15:00:00Z',
  ends_at: '2026-12-22T11:00:00Z',
  is_override_allowed: true,
  max_override_period_minutes: 90,
})
```

```bash cURL theme={"dark"}
device_id=$(jq -r '.device_id' <<< ${living_room})

# Create the climate presets.
curl -X 'POST' \
  'https://connect.getseam.com/thermostats/create_climate_preset' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
  \"device_id\": \"${device_id}\",
  \"climate_preset_key\": \"comfort\",
  \"name\": \"Comfort\",
  \"hvac_mode_setting\": \"heat\",
  \"heating_set_point_celsius\": 21
}"

curl -X 'POST' \
  'https://connect.getseam.com/thermostats/create_climate_preset' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
  \"device_id\": \"${device_id}\",
  \"climate_preset_key\": \"eco\",
  \"name\": \"Eco\",
  \"hvac_mode_setting\": \"heat\",
  \"heating_set_point_celsius\": 16
}"

# Set eco as the fallback climate preset.
curl -X 'POST' \
  'https://connect.getseam.com/thermostats/set_fallback_climate_preset' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
  \"device_id\": \"${device_id}\",
  \"climate_preset_key\": \"eco\"
}"

# Schedule the comfort preset for a guest's stay.
curl -X 'POST' \
  'https://connect.getseam.com/thermostats/schedules/create' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
  \"device_id\": \"${device_id}\",
  \"name\": \"Jane's stay\",
  \"climate_preset_key\": \"comfort\",
  \"starts_at\": \"2026-12-18T15:00:00Z\",
  \"ends_at\": \"2026-12-22T11:00:00Z\",
  \"is_override_allowed\": true,
  \"max_override_period_minutes\": 90
}"
```

```python Python theme={"dark"}
# Create the climate presets.
seam.thermostats.create_climate_preset(
    device_id=living_room.device_id,
    climate_preset_key="comfort",
    name="Comfort",
    hvac_mode_setting="heat",
    heating_set_point_celsius=21,
)

seam.thermostats.create_climate_preset(
    device_id=living_room.device_id,
    climate_preset_key="eco",
    name="Eco",
    hvac_mode_setting="heat",
    heating_set_point_celsius=16,
)

# Set eco as the fallback climate preset.
seam.thermostats.set_fallback_climate_preset(
    device_id=living_room.device_id, climate_preset_key="eco"
)

# Schedule the comfort preset for a guest's stay.
seam.thermostats.schedules.create(
    device_id=living_room.device_id,
    name="Jane's stay",
    climate_preset_key="comfort",
    starts_at="2026-12-18T15:00:00Z",
    ends_at="2026-12-22T11:00:00Z",
    is_override_allowed=True,
    max_override_period_minutes=90,
)
```

```ruby Ruby theme={"dark"}
# Create the climate presets.
seam.thermostats.create_climate_preset(
  device_id: living_room.device_id,
  climate_preset_key: "comfort",
  name: "Comfort",
  hvac_mode_setting: "heat",
  heating_set_point_celsius: 21,
)

seam.thermostats.create_climate_preset(
  device_id: living_room.device_id,
  climate_preset_key: "eco",
  name: "Eco",
  hvac_mode_setting: "heat",
  heating_set_point_celsius: 16,
)

# Set eco as the fallback climate preset.
seam.thermostats.set_fallback_climate_preset(
  device_id: living_room.device_id,
  climate_preset_key: "eco",
)

# Schedule the comfort preset for a guest's stay.
seam.thermostats.schedules.create(
  device_id: living_room.device_id,
  name: "Jane's stay",
  climate_preset_key: "comfort",
  starts_at: "2026-12-18T15:00:00Z",
  ends_at: "2026-12-22T11:00:00Z",
  is_override_allowed: true,
  max_override_period_minutes: 90,
)
```

```php PHP theme={"dark"}
// Create the climate presets.
$seam->thermostats->create_climate_preset(
    device_id: $living_room->device_id,
    climate_preset_key: "comfort",
    name: "Comfort",
    hvac_mode_setting: "heat",
    heating_set_point_celsius: 21,
);

$seam->thermostats->create_climate_preset(
    device_id: $living_room->device_id,
    climate_preset_key: "eco",
    name: "Eco",
    hvac_mode_setting: "heat",
    heating_set_point_celsius: 16,
);

// Set eco as the fallback climate preset.
$seam->thermostats->set_fallback_climate_preset(
    device_id: $living_room->device_id,
    climate_preset_key: "eco",
);

// Schedule the comfort preset for a guest's stay.
$seam->thermostats->schedules->create(
    device_id: $living_room->device_id,
    name: "Jane's stay",
    climate_preset_key: "comfort",
    starts_at: "2026-12-18T15:00:00Z",
    ends_at: "2026-12-22T11:00:00Z",
    is_override_allowed: true,
    max_override_period_minutes: 90,
);
```

```csharp C# theme={"dark"}
var deviceId = (string)livingRoom["device_id"]!;

// Create the climate presets.
await seam.PostAsync<JObject>(
    "/thermostats/create_climate_preset",
    new RequestOptions {
        Data = new {
            device_id = deviceId,
            climate_preset_key = "comfort",
            name = "Comfort",
            hvac_mode_setting = "heat",
            heating_set_point_celsius = 21
        }
    }
);

await seam.PostAsync<JObject>(
    "/thermostats/create_climate_preset",
    new RequestOptions {
        Data = new {
            device_id = deviceId,
            climate_preset_key = "eco",
            name = "Eco",
            hvac_mode_setting = "heat",
            heating_set_point_celsius = 16
        }
    }
);

// Set eco as the fallback climate preset.
await seam.PostAsync<JObject>(
    "/thermostats/set_fallback_climate_preset",
    new RequestOptions {
        Data = new { device_id = deviceId, climate_preset_key = "eco" }
    }
);

// Schedule the comfort preset for a guest's stay.
await seam.PostAsync<JObject>(
    "/thermostats/schedules/create",
    new RequestOptions {
        Data = new {
            device_id = deviceId,
            name = "Jane's stay",
            climate_preset_key = "comfort",
            starts_at = "2026-12-18T15:00:00Z",
            ends_at = "2026-12-22T11:00:00Z",
            is_override_allowed = true,
            max_override_period_minutes = 90
        }
    }
);
```

```java Java theme={"dark"}
// Uses the seamPost helper from Step 2.
String deviceId = "11111111-1111-1111-2222-444444444444";

// Create the climate presets.
seamPost("/thermostats/create_climate_preset",
    "{\"device_id\":\"" + deviceId + "\",\"climate_preset_key\":\"comfort\","
        + "\"name\":\"Comfort\",\"hvac_mode_setting\":\"heat\","
        + "\"heating_set_point_celsius\":21}");

seamPost("/thermostats/create_climate_preset",
    "{\"device_id\":\"" + deviceId + "\",\"climate_preset_key\":\"eco\","
        + "\"name\":\"Eco\",\"hvac_mode_setting\":\"heat\","
        + "\"heating_set_point_celsius\":16}");

// Set eco as the fallback climate preset.
seamPost("/thermostats/set_fallback_climate_preset",
    "{\"device_id\":\"" + deviceId + "\",\"climate_preset_key\":\"eco\"}");

// Schedule the comfort preset for a guest's stay.
seamPost("/thermostats/schedules/create",
    "{\"device_id\":\"" + deviceId + "\",\"name\":\"Jane's stay\","
        + "\"climate_preset_key\":\"comfort\","
        + "\"starts_at\":\"2026-12-18T15:00:00Z\","
        + "\"ends_at\":\"2026-12-22T11:00:00Z\","
        + "\"is_override_allowed\":true,"
        + "\"max_override_period_minutes\":90}");
```

```go Go theme={"dark"}
// Uses the seamPost helper from Step 2.
deviceID := livingRoom["device_id"]

// Create the climate presets.
seamPost("/thermostats/create_climate_preset", map[string]any{
    "device_id": deviceID,
    "climate_preset_key": "comfort",
    "name": "Comfort",
    "hvac_mode_setting": "heat",
    "heating_set_point_celsius": 21,
})

seamPost("/thermostats/create_climate_preset", map[string]any{
    "device_id": deviceID,
    "climate_preset_key": "eco",
    "name": "Eco",
    "hvac_mode_setting": "heat",
    "heating_set_point_celsius": 16,
})

// Set eco as the fallback climate preset.
seamPost("/thermostats/set_fallback_climate_preset", map[string]any{
    "device_id": deviceID,
    "climate_preset_key": "eco",
})

// Schedule the comfort preset for a guest's stay.
seamPost("/thermostats/schedules/create", map[string]any{
    "device_id": deviceID,
    "name": "Jane's stay",
    "climate_preset_key": "comfort",
    "starts_at": "2026-12-18T15:00:00Z",
    "ends_at": "2026-12-22T11:00:00Z",
    "is_override_allowed": true,
    "max_override_period_minutes": 90,
})
```

```bash Seam CLI theme={"dark"}
# Create the climate presets.
seam thermostats create-climate-preset --device_id "11111111-1111-1111-2222-444444444444" --climate_preset_key "comfort" --name "Comfort" --hvac_mode_setting "heat" --heating_set_point_celsius 21
seam thermostats create-climate-preset --device_id "11111111-1111-1111-2222-444444444444" --climate_preset_key "eco" --name "Eco" --hvac_mode_setting "heat" --heating_set_point_celsius 16

# Set eco as the fallback climate preset.
seam thermostats set-fallback-climate-preset --device_id "11111111-1111-1111-2222-444444444444" --climate_preset_key "eco"

# Schedule the comfort preset for a guest's stay.
seam thermostats schedules create --device_id "11111111-1111-1111-2222-444444444444" --name "Jane's stay" --climate_preset_key "comfort" --starts_at "2026-12-18T15:00:00Z" --ends_at "2026-12-22T11:00:00Z" --is_override_allowed true --max_override_period_minutes 90
```

For more about presets and schedules, see [Creating and Managing Climate Presets](https://www.seam.co/docs/capability-guides/thermostats/creating-and-managing-climate-presets.md) and [Creating and Managing Thermostat Schedules](https://www.seam.co/docs/capability-guides/thermostats/creating-and-managing-thermostat-schedules.md).

***

## Step 5: Connect a real Tado thermostat

Now that you have learned the basics of using the Seam API, you can connect and control a real Tado thermostat. To do so, switch to a [non-sandbox workspace](https://www.seam.co/docs/core-concepts/workspaces.md#production-workspaces) and [API key](https://www.seam.co/docs/core-concepts/authentication/api-keys.md).

For the steps your users follow to approve Seam in Tado, see the [Tado setup guide](https://www.seam.co/docs/device-and-system-integration-guides/tado-thermostats/tado-setup-guide.md).

***

## Step 6: Build your application!

The Seam API and Seam SDKs give you up-to-date information about your thermostats. Seam also sends thermostat-related events that let you monitor your thermostats and the connected heating and cooling systems. Our [simulation endpoints](https://www.seam.co/docs/capability-guides/thermostats/testing-your-thermostat-app-with-simulate-endpoints.md) help you test your app against events that are hard to reproduce with real devices.

***

## Next steps

Now that you've completed this getting started guide for Tado devices, you can learn more about what you can do with the Seam API.

* [ ] **Explore**\
  See the [other devices and system integrations](https://www.seam.co/docs/device-and-system-integration-guides.md) that Seam supports.
* [ ] **Learn**\
  Read about Seam [concepts](https://www.seam.co/docs/core-concepts/overview.md) and the [device and system capabilities](https://www.seam.co/docs/capability-guides/device-and-system-capabilities.md) that Seam supports.
* [ ] **Expand your abilities**\
  Find out what other [thermostat actions](https://www.seam.co/docs/capability-guides/thermostats.md) you can perform using the Seam API.
* [ ] **Use webhooks**\
  Learn how to use [webhooks](https://www.seam.co/docs/developer-tools/webhooks.md) as an efficient way to receive device events.

> [!NOTE]
>
> If you have any questions or want to report an issue, email us at
> [support@seam.co](mailto:support@seam.co).

***

## Quick links

> [card] [Get an API Key (free)](https://console.seam.co/)
>
> Sign up for the Seam Console and get your API keys. →

> [card] [Contact Sales](https://www.seam.co/contact-us)
>
> Got a project or a specific question? Contact our team to get answers. →


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.