Tellihealth logo
API docs by Redocly

Tellihealth RPM API (2.0.0)

Download OpenAPI specification:Download

License: MIT

Last updated on 10-15-2024

Telli Health Developer's Guide and Specifications

Welcome to the Telli Health Developer Guide, which will guide you through the Telli Health integration process, and focuses on how to get data from, or send data to, Telli Health's patient monitoring devices.

Device Generations Overview

Telli Health has Generation 1 and Generation 2 patient monitoring devices in circulation.

  • Generation 1 devices send basic reading data to the platform in a unidirectional method using HTTPS.
  • Generation 2 devices use secure bi-directional messaging to send readings, device data, checkin (AKA heartbeat) messages, and acknowledgments to the platform. The Gen2 devices can receive settings requests, which may vary based on the models' capabilities.

Devices that currently support Gen2 capabilities: TelliBP01

To provide a seamless transition between API versions and device generations, readings from either generation device are cross-compatible with either API version endpoint. Therefore, Gen1 device readings can be received on API v2 endpoints, and Generation 2 device readings can be received on existing API v1 endpoints.

NOTE: Other Gen2 device capabilities and data are NOT supported on API v1 endpoints.

Getting Started

It is easy to integrate with our hardware before purchasing Telli Health devices. The OpenAPI specification provides the information needed to develop ingestion slugs and control interfaces.

Telli Health highly recommends creating a single endpoint for all message types or a single endpoint slug for each message type, such as readings, heartbeat messages, or setting acknowledgements. The endpoint should parse and handle the inbound data based on the message type in the schema object.

For full system functionality, the platform developer must provide Telli Health with the following information:

  • The enabled slug endpoint or endpoints;
  • The API version currently supported, and
  • The API key required to access the HTTPS endpoint while sending information.

In exchange, Telli Health provides the developer with an API key for calling the endpoint(s) on the Telli Health platform.

After you purchase Telli Health devices, you will receive an email containing the Device ID and Serial number for the device(s); you must match each device to a user on your platform.

Data Transmission Overview

All integrations must be able to receive readings via the readings webhook. As Telli Health’s listener receives readings, Telli Health's data gateway sends your data to the POST URL in your profile in near real-time by HTTPS POST. Telli Health’s POST will come from multiple US – East Amazon Cloud Storage IP addresses.

For high availability, data packets are replicated in a Telli Health Secure Database in the event of system outages. Contact Telli Health support if you require a playback of your device readings data.

Authentication and Token Management

The Telli Health platform recommends that you authenticate and secure inbound and outbound connections.

Successful authentication creates a token that grants access to protected resources. To secure your connection, request an authentication token that you can add to all headers: 

x-api-key: \<token\>

Contact Telli Health support to enable authentication.

V1 model

V1 webhook model

V1 readings data - to be deprecated Webhook

Device behavior description

A Gen1 device delivered a new reading to the Telli Health platform.
Reading value messages are delivered when:

  1. The user activates the device,
  2. The user takes a measurement,
  3. The device can read the current time, and
  4. The device acknowledges that the data was sent to the platform.

Reading transmission types include Blood Pressure, Blood Glucose, Weight Scale, SpO2 Pulse Oximetry, Peak Flow, Thermometer, Sleeping Mat Activity, and Sleeping Mat Duration.

Sleep and Resting Heart Rate Monitor

Both the Sleeping Mat Activity and Sleeping Mat Duration readings provide data for Telli Health's sleep mat and resting heart monitor service.

Sleeping Mat Activity provides data collected every four hours during a fixed 12-hour interval between 8 p.m. (20:00) and 8 a.m. (08:00). Sleep mat averages are taken while the mat is in use. Sampling is paused if a user gets out of bed without the mat being active.

Sleeping Mat Duration provides data collected at the end of the sleep interval.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
required
BloodPressureData (object) or BloodGlucoseData (object) or WeightData (object) or SpO2Data (object) or TemperatureData (object) or PeakFlowData (object) or SleepingMatActivityData (object) or SleepingMatDurationData (object)
deviceId
required
string

Represents the device identifier mostly IMEI.

readingType
required
string
Enum: "BloodPressure" "BloodGlucose" "Weight" "SpO2" "Temperature" "PeakFlow" "SleepingMatActivity" "SleepingMatDuration"

Represents the reading type.

time
required
string <int64>

Unix timestamp in milliseconds

Responses

Request samples

Content type
application/json
Example
{
  • "data": {
    },
  • "deviceId": "864593054464085",
  • "readingType": "BloodPressure",
  • "time": "1721382524000"
}

V2 model

V2 webhook model

A new heartbeat has been received from the device Webhook

Device behavior description

A new heartbeat was received from the device.

By default, Gen2 devices send 3 heartbeats per 24-hour period, or one heartbeat every 8 hours. The heartbeat timer resets each time a device is operated; therefore, the next heartbeat will be received +8 hours from the device's last successful operation. Currently, this behavior applies only to TelliBP01.

For example, if a user takes one reading per day, then depending on connectivity and sufficient battery, expect the device to receive one reading and two heartbeats during that day.

Gen2 devices capable of alert reminders must have the alert reminder enabled with a set start and stop time. The reminder stop time must be at least one hour later than the reminder start time. When a device is in reminder mode (for example, if the start time is 08:00 and it is now 08:05), the heartbeat message will be delayed until the reminder is cleared.

Authorizations:
apiKeyAuth
Request Body schema: application/json

Heartbeat from the device

type
required
string
Value: "Heartbeat"

Represents the reading type.

deviceId
required
string^\d{15}$

The IMEI of the device

time
required
string <integer>

Response time from the device in epoch format

tzOffsetMinutes
required
string <integer> ^(-)?\d+$

UTC offset in minutes

genVer
required
string <string>
Value: "2"

The device generation version

required
object (Devdata)

Provides device metadata, including information such as battery level, signal strength, and more.

Responses

Request samples

Content type
application/json
{
  • "type": "Heartbeat",
  • "deviceId": "864581069137614",
  • "time": "string",
  • "tzOffsetMinutes": "-200",
  • "genVer": "2",
  • "devdata": {
    }
}

User has cleared the reminder on the device Webhook

Device behavior description

The user manually cleared the adherence reminder on the device without taking a reading.

A manually cleared message alert is delivered to the Telli Health platform from the device when:

  1. The device is in alert or adherence reminder mode,
  2. The user uses a documented pattern of buttons to cancel the alert, and
  3. The device can read the current time.
Authorizations:
apiKeyAuth
Request Body schema: application/json

Cleared reminder from the device

type
required
string
Value: "ReminderCleared"

Represents the reading type.

deviceId
required
string^\d{15}$

The IMEI of the device

time
required
string <integer>

Response time from the device in epoch format

tzOffsetMinutes
required
string <integer> ^(-)?\d+$

UTC offset in minutes

genVer
required
string <string>
Value: "2"

The device generation version

required
object (Devdata)

Provides device metadata, including information such as battery level, signal strength, and more.

Responses

Request samples

Content type
application/json
{
  • "type": "ReminderCleared",
  • "deviceId": "864581069137614",
  • "time": "string",
  • "tzOffsetMinutes": "-200",
  • "genVer": "2",
  • "devdata": {
    }
}

The device responded to settings change request Webhook

Device behavior description

A device responded to a settings change request.

Gen2 devices may receive settings for reminder alerts. Since the device may be off at the time the settings are sent, this message is delivered asynchronously. The device responds during its next successful connection session. When the platform receives an acknowledgement (ACK) from the device, the platform publishes an ACK to the registered endpoint.

Authorizations:
apiKeyAuth
Request Body schema: application/json

The device response to the settings change request

type
required
string
Value: "SettingsResponse"

Represents the reading type.

deviceId
required
string^\d{15}$

The IMEI of the device

time
required
string <integer>

Response time from the device in epoch format

tzOffsetMinutes
required
string <integer> ^(-)?\d+$

UTC offset in minutes

genVer
required
string <string>
Value: "2"

The device generation version

status
required
string
Enum: "ACK" "NACK"

ACK - means the device acknowledged the change, and NACK means it did not

Responses

Request samples

Content type
application/json
{
  • "type": "SettingsResponse",
  • "deviceId": "864581069137614",
  • "time": "string",
  • "tzOffsetMinutes": "-200",
  • "genVer": "2",
  • "status": "ACK"
}

V2 readings data - updated user model Webhook

Device behavior description

A Gen2 device delivered a new reading to the Telli Health platform.
Reading value messages are delivered when:

  1. The user activates the device,
  2. The user takes a measurement,
  3. The device can read the current time, and
  4. The device acknowledges that the data was sent to the platform.

OR

  1. The device is activated by a heartbeat,
  2. The device can read the current time,
  3. A measurement is stored in the device’s memory, and
  4. The device acknowledges that the data was sent to the platform.

Reading transmission types include Blood Pressure, Blood Glucose, Weight Scale, SpO2 Pulse Oximetry, Peak Flow, Thermometer, Sleeping Mat Activity, and Sleeping Mat Duration.

Sleep and Resting Heart Rate Monitor

Both the Sleeping Mat Activity and Sleeping Mat Duration readings provide data for Telli Health's sleep mat and resting heart monitor service.

Sleeping Mat Activity provides data collected every four hours during a fixed 12-hour interval between 8 p.m. (20:00) and 8 a.m. (08:00). Sleep mat averages are taken while the mat is in use. Sampling is paused if a user gets out of bed without the mat being active.

Sleeping Mat Duration provides data collected at the end of the sleep interval.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
required
BloodPressureData (object) or BloodGlucoseData (object) or WeightData (object) or SpO2Data (object) or TemperatureData (object) or PeakFlowData (object) or SleepingMatActivityData (object) or SleepingMatDurationData (object)

Holds the reading data

deviceId
required
string

Represents the device identifier mostly IMEI.

readingType
required
string
Enum: "BloodPressure" "BloodGlucose" "Weight" "SpO2" "Temperature" "PeakFlow" "SleepingMatActivity" "SleepingMatDuration"

Represents the reading type.

time
required
string^\d+$

Unix timestamp in milliseconds

tzOffsetMinutes
required
string or null^(-)?\d+$

UTC offset in minutes. null is provided if the device does not support this data

genVer
required
string
Enum: "1" "2"

The device generation version

mem
required
string or null
Enum: "0" "1"

Indicates if the reading if a memory "1" or a nomal "0" or null if value not provided by the device

required
Devdata (object) or null

Contains device metadata like radious, battery level and cycles. It could be null if the device does not support this data

Responses

Request samples

Content type
application/json
Example
{
  • "data": {
    },
  • "deviceId": "864593054464085",
  • "readingType": "BloodPressure",
  • "time": "1721382524000",
  • "mem": "0",
  • "tzOffsetMinutes": "-200",
  • "genVer": "2",
  • "devdata": {
    }
}

Manage device settings

Change the device settings.

Updates the device settings

Device behavior description

The device’s settings will be updated.

Gen2 devices may receive settings for the reminder alerts. Since the device may be off at the time the settings are sent, this message is delivered asynchronously. The device responds during its next successful connection session. When the platform receives an acknowledgement (ACK) from the device, the platform publishes an ACK to the registered endpoint. When the settings endpoint is called between ACK messages, the settings value updates to the newly requested value.

An alert setting will not activate for a time set in the past, but will remain inactive until it's set time is reached during the next alert timeframe. For example, if the start time is 08:00 and it is now 08:05, the alert message will be delayed until 08:00 on the following day.

Authorizations:
apiKeyAuth
path Parameters
deviceId
required
string^\d{15}$

The IMEI of the device

Request Body schema: application/json
required
enabled
required
boolean

Enable or disable alarms on the device

arstart
required
string^[0-2][0-9][0-5][0-9]$

Defines when the device alarm should be started at. The format is in HH:MM

arstop
required
string^[0-2][0-9][0-5][0-9]$

Defines when the device alarm should be stopped at. The format is in HH:MM

Responses

Request samples

Content type
application/json
{
  • "enabled": "true",
  • "arstart": "1100",
  • "arstop": "1230"
}

Response samples

Content type
application/json
{
  • "message": "Validation error",
  • "errors": [
    ]
}