Getting Started with the Device Management API

In this chapter, you will find practical examples showing how to perform the most important operations with our Device Management API.

Getting Started with Device Management API

This tutorial guides you through using the core functions of our Device Management API with a setup of two typical devices.

The procedures introduced here can be applied to other supported devices, though specific steps may vary depending on device types and firmware versions.

We have chosen this particular setup because it represents one of the more challenging configurations. The gateway and sensor used have no display to provide status feedback. The only indicators are the blinking patterns of one or two LEDs, which can be difficult to interpret for first-time users.

Tip

Every time we make a request in postman we provide a template which you can simply copy into postman.

This will look like: GET https://device-management-api.<region>.<environment>.savr.saveris.net/devcies?site=<your-site>

You have to set the HTTP method in postman to GET and paste the url in the text field. You have to customize the fields region, environment and your-site.

1. Requirements

To complete this tutorial, you will need:

One Gateway (Wireless Sensor) - type name: testo 164 Gateway
One Wireless Sensor (the specific type is not relevant; we use the DC version) - type name: testo 164 DC
Postman or comparable software to make HTTP requests
API Account - If you need one or you have forgotten your password, please refer to the contact page for more details
Wifi Access

We recommend reading the general Authentication & Security and Concepts sections before proceeding with this getting started guide. Understanding these foundational elements will make it much easier to follow this tutorial and implement the API successfully.

2. Verify Your API Access

First, confirm that you can connect to the Device Management API using your API account. We'll start by obtaining a bearer token, which is required for subsequent API requests. For this example, we're using the integration stage in our URL. Please customize this for your desired endpoint.

In Postman, the prepared request will look like this:

As shown, there is a small JSON object embedded in the request body. This is where you need to enter your API account credentials.

After a successful request, the response in Postman should look like this:

Now you can copy the value from the IdToken field. This is your bearer token, which remains valid for 24 hours.

3. Create a New Site

With a new account, you must first create a site, as each device is associated with a site. The site identifier is a required parameter in all subsequent API requests. For more information about sites and other concepts, please refer to the concepts page.

To create a site, prepare a new POST request. Paste your bearer token in the Authorization tab and ensure the authorization type is set to 'Bearer Token'. Use the /connect-keys endpoint to generate both the site and its related connect key. The connect key will be used later to onboard devices to this site.

In the request, add a URL parameter as a key-value pair containing the site name you wish to create. The site name can be any character string.

The prepared request will look like this:

Endpoint template:

POST https://device-management-api.<region>.<environment>.savr.saveris.net/connect-keys?site=<your-site>

In Postman:

The response will return the site and its related connect key:

You can retrieve the site and its connect key again by making a GET request to the same endpoint instead of a POST.

4. Onboard the Gateway

To verify that no devices are currently associated with your new site, you can make a GET request to the devices endpoint. The prepared request with its authorization properties will look like this in Postman:

Endpoint template:

GET https://device-management-api.<region>.<environment>.savr.saveris.net/devices?site=<your-site>

You will see an empty device list in the JSON response for your new site.

Now you have to prepare your gateway. For this you have to connect the gateway via USB to your PC.

Tip

To configure your gateway we suggest using a Windows device with Adobe Acrobat installed or to use our new app.

If the connection was successful you will see a new volume called 'GATEWAY' in your file manager. On this volume you will find a PDF file. Open it. The PDF will look similar to this one. Slight changes are possible depending on the logger/gateway firmware version.

Please enter your connect-key into the field 'Account ID', which you have received in the connect-key request one step before. Additionally you have to set the SSID (name of your Wifi) for your wifi network and the security type and the password for your Wifi. The password field will appear if you set the security type.

If you have prepared all fields click on the button 'Save configuration' and store the file back to the volume. Now disconnect the gateway. If the gateway is powered by batteries it will restart now. If you power it over USB, connect it to the original testo power supply. Don't power it over a device like a laptop, because then the logger will again start in the config mode which is not what we want.

After a short time (20-30 seconds) the network status LED will stop blinking and light up continuously.

Now you can make the GET devices request again. The response should contain your gateway and will look similar to this:

Endpoint template:

GET https://device-management-api.<region>.<environment>.savr.saveris.net/devices?site=<your-site>

Well done! You have onboarded your gateway.

5. Onboard the Sensor

The onboarding of a sensor is much easier. In this tutorial we use a door contact sensor, but you can use any sensor you want.

First you have to request all sensors from your site. Similar to the devices request you will get an empty list as response if you have no devices registered.

Endpoint template:

GET https://device-management-api.<region>.<environment>.savr.saveris.net/sensors?site=<your-site>

To pair your sensor you have to click shortly on the button on the gateway. The sensor status LED will light up continuously. The gateway is now in pairing mode for a short time.

Now click shortly on the pairing button on the sensor. The status LED will blink green one time.

After a few seconds (typically 3 to 30 seconds) the sensor should pair itself with the gateway. The status LEDs won't give you a hint if the pairing was successful. To check this, request all sensors over our API again.

Endpoint template:

GET https://device-management-api.<region>.<environment>.savr.saveris.net/sensors?site=<your-site>

If the pairing was successful you will see in the response a json which contains a sensor configuration. You can compare the sensor serial number to ensure all has worked properly.

6. Create a Measurement Object

The sensor has to be related to a measurement object. This measurement object can be something like a fridge, cooling room, oven or something else which has parameters that can be logged by our devices. In this tutorial we use a door contact sensor. A typical use case for a door contact sensor is to log the state of a cooling room door. So we want to create a cooling-room-1 measurement object which is related to our door contact sensor.

We'll first make a GET request to ensure we have no measurement objects at our site.

Endpoint template:

GET https://device-management-api.<region>.<environment>.savr.saveris.net/measuring-objects?site=<your-site>

The expectation is that we get an empty list of measurement objects.

If that was done successfully, we create the measurement object with a call to the endpoint:

Endpoint template:

POST https://device-management-api.<region>.<environment>.savr.saveris.net/measuring-objects?site=<your-site>

The request contains a JSON in its body. This can look like this:

{done
  "back_reference": "cooling-room-1",
  "measuring_setup": {
    "channel_assignments": [
      {
        "logical_channel": {
          "physical_property": {
            "physical_value": "UNKNOWN", // depends on the channel for your measurement object
            "extension": "SWITCH"        // depends on the channel for your measurement object
          },
          "ordinal": 0
        },
        "sensor_channel": {
          "physical_property": {
            "physical_value": "UNKNOWN", // depends on the capabilities of your sensor channels
            "extension": "SWITCH"        // depends on the capabilities of your sensor channels
          },
          "sensor_uuid": "<uuid from your get sensors request before>"
        }
      }
    ]
  }
}

Attention

When configuring your measurement object, the system will not automatically detect incorrect values for the sensor_uuid or channel properties. The API does not return error messages in these cases. Please carefully verify that your sensor UUID and channel properties are correct before proceeding. You can validate your configuration afterwards by checking if measurements are being properly recorded.

The most important parts are the configuration of the channels and the sensor_uuid. The sensor_uuid comes from our request response where we have gotten the list of all sensors at our site. The sensor_uuid is the reference to relate the measuring object and the sensor. The channel config is a mapping between the real sensor channel and the measuring object channel. This makes sense because a measuring object can have more than one property which you want to measure. So it is possible that one sensor isn't enough to measure all these properties. For example, our cooling-room-1 could have its door state and additionally its temperature, which we cannot measure with our door contact sensor.

You have to ensure that the physical_properties are related to the capabilities of your sensor. If you look in the response of your GET sensors request, you will find a section in the JSON response which contains this channel information. For example:

{
    "sensors": [
        {
            "uuid": "505a5669-fa75-4baa-a02d-ff537aba7ead",
            "firmware": {
                ...
            },
            "valid_from": "2025-04-08T08:15:48.306Z",
            "customer_site": "0001",
            "serial_number": "56048164",
            "model_code": "0572 2203 01",
            "device_connection": {
                ...
            },
            "capability": {
                ...
            },
            "setting": {
                ...
            },
            "status": {
                ...
            },
            "channels": [
                {
                    "channel_number": 0,
                    "physical_property": {
                        "physical_value": "PV_UNKNOWN",
                        "extension": "PVE_SWITCH"
                    },
                    "physical_unit": "PU_NUMBER",
                    "resolution_exponent": 0,
                    "capability": {
                        "calibration_support": false,
                        "sum_source": false,
                        "trigger_source": false,
                        "product_simulation_support": false
                    },
                    "setting": {
                        "display_physical_unit": "PU_NUMBER",
                        "trigger_configs": []
                    }
                }
            ]
        }
    ]
}

All possible property details are documented in our API reference. So look in to the API if you require more details.

If the request was successful you will get as response the UUID of the measurement object.

Response:

{
    "uuid": "df6db54b-8b06-4cb2-bd72-67f878cf386b"
}

7. Whats next

Well done! You have onboarded your first sensor and you have associated it with a measurement object. You can continue with the realtime API to assign alarms to the channels of your measurement object to get notifications in realtime or continue with the data API to get the data history from your sensor or measurement object. You will find the links to the further tutorials below:

Help

API Request returns 401 Unauthorized

If you encounter a 401 Unauthorized error when making API requests, please verify your authentication settings. This issue commonly occurs when creating new requests in Postman, as the authentication method may reset to a default value. Ensure that:

The authentication method is set to "Bearer Token"
Your token is correctly entered and has not expired
The token is properly formatted without any additional characters or spaces

Checking these authentication details will typically resolve most 401 Unauthorized errors and allow your requests to proceed successfully.

Device or Logger will not connect

Troubleshooting connection issues

If your logger fails to connect, please try the following steps:

Proper Button Press: Ensure you press the pairing buttons with sufficient pressure but very briefly, especially when pairing sensors. A light, quick press is often more effective than a longer one.
Device Reset: If connection problems persists, you can reset the device by pressing and holding the pairing button for more than 30 seconds. After the reset, you'll need to reconfigure the device following the steps outlined above.
Support Contact: If you continue to experience connection issues after trying these steps, please contact our technical support team via email.