Skip to content

Getting Started with the Smart Connect API

This tutorial introduces you to the Smart Connect API, which provides access to your measurement data, alarms, device information, locations and measuring objects. Rather than simply listing API calls, we'll explore real-world scenarios that demonstrate when and why to use different endpoints. The tutorial is structured by typical customer use cases and each tutorial is independent. You can simply select a tutorial that best fits your current use case. You see all use cases in the right nav bar.

Overview

The Smart Connect API serves as your window into historical data across your monitoring system. Whether you need temperature measurements from last week, a record of all alarms from the past month, or an overview of your device status - the Smart Connect API provides these insights through asynchronous methods. Before proceeding, ensure you're familiar with the concepts presented in the Authentication & Security and Concepts documentation.

Requirements

To follow this tutorial, you'll need:

  • A valid API key — see Authentication & Security on how to generate one
  • An API client such as Postman, or an equivalent tool, for making API requests
  • At least one device set up and sending data in Smart Connect

Introduction

The Smart Connect API offers an asynchronous approach for retrieving data, designed for different scenarios:

When to Use Asynchronous Endpoints

Asynchronous endpoints are designed for retrieving larger datasets that might take time to prepare. Instead of waiting for all data to be gathered, these endpoints work in two steps: First, you make a request to start the data preparation process. The API responds with a request identifier. Then, you periodically check whether your data is ready using that identifier. Once ready, you can download the results as files. Asynchronous endpoints are the right choice when:

  • Retrieving larger data covering a time period more than a few seconds
  • Working with sites that have many devices
  • Needing to download data in specific file formats for analysis (CSV, PARQUET)

Retrieving Temperature History for Compliance Reports

When preparing compliance reports or investigating temperature excursions, you'll need historical measurement data. For longer time periods or multiple devices, the asynchronous approach is necessary. To retrieve historical measurement data: First, initiate the data preparation with a POST request to the measurements endpoint: POST https://data-api.REGION.ENV.smartconnect.testo.com/v2/measurements In the request body, specify the time period you're interested in: 

{
  "date_time_from": "2025-04-01T00:00:00Z",
  "date_time_until": "2025-04-15T23:59:59Z",
  "options": {
    "result_file_format": "CSV"
  }
}
After sending this request, you'll receive a response containing a unique identifier for your data preparation request: 
{
  "status": "Submitted",
  "request_uuid": "5f330649-9cf2-4d3d-8c96-9e4b2d960678"
}
Now, check if your data is ready by creating a GET request with the request UUID from the previous response: GET https://data-api.REGION.ENV.smartconnect.testo.com/v2/measurements/<request_uuid> Initially, the status will show as "In Progress". 
{
  "status": "In Progress"
}
Continue checking periodically until you see: 
{
  "status": "Completed",
  "data_urls": [
    "https://...s3.amazonaws.com/measurements/...csv?..."
  ],
  "metadata_url": "https://...s3.amazonaws.com/measurements/...csv.metadata?..."
}
Once completed, download the files using the provided URLs. The CSV file will contain all measurements for the specified time period, which you can then use for your compliance reports or analysis.

Reviewing Past Alarm Events for Root Cause Analysis

When investigating incidents or preparing for audits, you may need to review historical alarm events. These records show when values exceeded thresholds or when system issues occurred. To retrieve alarm history, start a data preparation request for alarm data: POST https://data-api.REGION.ENV.smartconnect.testo.com/v3/alarms Specify the relevant time period in the body of the request. For example: 

{
  "date_time_from": "2025-04-01T00:00:00Z",
  "date_time_until": "2025-04-15T23:59:59Z",
  "options": {
    "result_file_format": "CSV"
  }
}
After sending this request, you'll receive a response containing a unique identifier for your data preparation request: 
{
  "status": "Submitted",
  "request_uuid": "fbf29fed-e3e2-46fb-a304-ee099e849044"
}
Now, check if your data is ready by creating a GET request with the request UUID from the previous response: GET https://data-api.REGION.ENV.smartconnect.testo.com/v3/alarms/{request_uuid} Initially, the status will show as "In Progress". Continue checking periodically until the status changes to "Completed". When ready, download the data file, which will contain alarm records including:

  • Alarm time and reason
  • Affected device or sensor
  • Alarm severity
  • Measured values that triggered the alarm

This information is valuable for identifying patterns in alarm events or demonstrating compliance with monitoring requirements during audits.

Understanding Device Properties

For a comprehensive understanding of your devices' capabilities and settings, the device properties endpoint provides detailed metadata. Initiate a data preparation request: POST https://data-api.REGION.ENV.smartconnect.testo.com/v3/devices/properties with your desired file format: 

{
  "options": {
    "result_file_format": "CSV"
  }
}
Check the status until the data is ready: GET https://data-api.REGION.ENV.smartconnect.testo.com/v3/devices/properties/{request_uuid} The device properties data includes:

  • Detailed information about each device and its sensors
  • Channel configurations and measurement capabilities
  • Physical units and measurement types
  • Calibration status and possibilities
  • Relationships to equipment

This information is valuable for documentation purposes and for understanding the full capabilities of your monitoring system.

Understanding Locations

For a comprehensive understanding of your registered locations, the locations endpoint provides related information. Initiate a data preparation request: POST https://data-api.REGION.ENV.smartconnect.testo.com/v1/locations with your desired file format: 

{
  "options": {
    "result_file_format": "CSV"
  }
}
Check the status until the data is ready: GET https://data-api.REGION.ENV.smartconnect.testo.com/v1/locations/{request_uuid} The locations data includes:

  • Location name
  • Information about the owner (tenant_uuid) and the parent location (parent_uuid)
  • The type of the location and its parent (e.g., Customer, Measurement site), as well as a more specific subtype for the location itself (e.g., Ventilation, Flue gas).

Understanding Measuring Objects

For a complete view of your measuring objects, the measuring objects endpoint exposes detailed information. Initiate a data preparation request: POST https://data-api.REGION.ENV.smartconnect.testo.com/v1/measuring-objects with your desired file format: 

{
  "options": {
    "result_file_format": "CSV"
  }
}
Check the status until the data is ready: GET https://data-api.REGION.ENV.smartconnect.testo.com/v1/measuring-objects/{request_uuid} The measuring objects data includes:

  • Information about the owning customer (customer_uuid) and the customer site (customer_site).
  • The product family ID (product_family_id) such as savr, sav3, and data layer.
  • The corresponding configurations including measurement alarm configuration, channel assignments, and measuring instructions.

This information is essential for understanding a measuring object in detail, including its owning customer, product family ID, and related configurations.

What's Next?

Now that you've worked through the core use cases, here are the natural next steps:

  • Examples — Copy-paste-ready curl examples for every endpoint, including OData filtering for alarms, device status, and locations
  • API Reference — Full schema documentation with all available fields, request parameters, and response structures
  • Concepts — A deeper look at the asynchronous request model, status values, and file format options

Troubleshooting

API Request Returns 401 Unauthorized

If you encounter a 401 Unauthorized error, check that:

  • Your API key is valid and hasn't expired
  • The x-custom-api-key header is included in every request
  • The key is correctly copied without extra spaces or characters

Asynchronous Request Taking Too Long

For asynchronous requests that seem to take too long:

  • Verify your network connection is stable
  • Consider requesting smaller time ranges
  • Allow more time for processing large datasets