Device Reports Common Schema

Common Schema Structure

This document outlines the authoritative common schema structure for data reports generated by Sensos devices, including the Sensos Smart Label.

Data delivery rules (Webhooks and customer integrations) stream this payload in real time as devices transmit periodic heartbeats, movement alerts, sensor excursions, or milestone events.

Below is an example of the common JSON report structure used in data delivery:

Example JSON Report

{
  "messageId": "c961ea64-9e56-4e31-b563-de8ece738370",
  "deviceId": "351521100750611",
  "accountId": "83298196-0d7a-4f45-9a06-a3e92c35a090",
  "timestamp": "2026-09-15T12:32:14Z",
  "type": "SensosLabelMessage",
  "messageCount": 89,
  "device": {
    "partNumber": "SLS-10001F-00-B-00",
    "softwareVersion": "1.6"
  },
  "location": {
    "source": "Cellular",
    "latitude": 50.00350791,
    "longitude": 22.05932459,
    "accuracy": 568,
    "country": "Poland"
  },
  "trigger": {
    "main": "TemperatureAlert",
    "list": [
      "TemperatureAlert",
      "Static",
      "SavedReport"
    ]
  },
  "sensors": {
    "deviceTemperature": 10.0,
    "humidity": 52.3,
    "isSealClosed": true,
    "light": 120,
    "isLightBreached": false,
    "accelerometer": {
      "xAxis": 0,
      "yAxis": 32,
      "zAxis": 976
    }
  },
  "battery": {
    "voltage": 2989,
    "percentage": 87,
    "remainingReports": 261
  },
  "features": {
    "shock": {
      "timestamp": "2026-09-15T12:30:00Z",
      "counter": 2,
      "magnitude": 12.4,
      "duration": 40,
      "magnitudeThreshold": 10000,
      "durationThreshold": 80
    }
  }
}

Data Report Schema Fields

Field Name	Description	Type	Units	Detailed Description	Nullable
`messageId`	Report Message ID	String (UUID)	—	Unique identifier generated for every individual report event.	No
`deviceId`	Device Identifier	String	—	Identifier of the reporting hardware. For Sensos Smart Labels, this is the 15-digit cellular IMEI string (e.g. `"351521100750611"`).	No
`accountId`	Account Identifier	String (UUID)	—	The operational Sensos account ID that the reporting device belongs to.	No
`timestamp`	Report Timestamp	String	ISO 8601	Time the measurement was recorded on the device, represented in UTC (`YYYY-MM-DDTHH:mm:ssZ`).	No
`type`	Message Type	String	—	Protocol message discriminator. Fixed to `"SensosLabelMessage"` for device reports.	No
`messageCount`	Message Sequence Counter	Integer	—	Monotonically increasing counter incremented with every report transmission attempt.	Yes
`device.partNumber`	Device Part Number	String	—	Commercial hardware model/part number (e.g., `"SLS-10001F-00-B-00"` or `"SLS-2000-00-B-10"`).	Yes
`device.softwareVersion`	Firmware Version	String	—	Firmware version string running on the device micro-controller (e.g., `"1.4"`, `"1.6"`).	Yes
`location.source`	Positioning Source	String	—	Positioning technology used to determine coordinates: `"Cellular"`, `"GPS"`, `"Wifi"`, or `"BleGateway"`.	Yes
`location.latitude`	Latitude	Decimal / Float	Degrees	Device geographical latitude in decimal degrees.	Yes
`location.longitude`	Longitude	Decimal / Float	Degrees	Device geographical longitude in decimal degrees.	Yes
`location.accuracy`	Positioning Accuracy	Integer	Meters	Estimated horizontal accuracy radius in meters (67% confidence interval).	Yes
`location.country`	Country Name	String	—	Country name resolved from cellular network MCC or reverse geolocation.	Yes
`trigger.main`	Primary Trigger	String	—	Primary event condition that triggered the transmission (e.g., `"TemperatureAlert"`, `"Shock"`, `"Movement"`).	Yes
`trigger.list`	Evaluated Triggers	Array of Strings	—	List of all trigger conditions evaluated during this transmission interval.	Yes
`sensors.deviceTemperature`	Ambient Temperature	Decimal / Float	°C	Calibrated temperature reading with a range of -30°C to +70°C and 0.1°C resolution.	Yes
`sensors.humidity`	Relative Humidity	Decimal / Float	%RH	Relative humidity reading from 0% to 100% with 0.1% resolution.	Yes
`sensors.isSealClosed`	Physical Seal State	Boolean	—	State of the continuous conductive seal loop: `true` (Intact / Sealed), `false` (Broken / Tampered).	Yes
`sensors.light`	Ambient Light	Integer	Lux	Ambient illumination intensity in lux (calculated as raw sensor ADC × 4). Emitted when ambient light telemetry is enabled for the account.	Yes
`sensors.isLightBreached`	Light Tamper Alarm	Boolean	—	`true` if ambient light exceeds the darkness arming threshold (indicating container or parcel breach); `false` if armed/unarmed and intact; `null` if unconfigured.	Yes
`sensors.accelerometer.xAxis`	X-Axis Acceleration	Integer	mg	Instantaneous linear acceleration along the X-axis in milli-G (mg).	Yes
`sensors.accelerometer.yAxis`	Y-Axis Acceleration	Integer	mg	Instantaneous linear acceleration along the Y-axis in milli-G (mg).	Yes
`sensors.accelerometer.zAxis`	Z-Axis Acceleration	Integer	mg	Instantaneous linear acceleration along the Z-axis in milli-G (mg).	Yes
`battery.voltage`	Cell Voltage	Integer	mV	Instantaneous battery terminal voltage in millivolts. Primary indicator of electrical power reserve.	No
`battery.percentage`	Battery Percentage	Integer	%	Estimated State of Charge (SoC) from 0% to 100%. Emitted when battery percentage calculation is enabled for the tenant.	Yes
`battery.level`	Battery Level Category	String	—	Categorical battery status (`"Low"`, `"Medium"`, `"High"`, `"Full"`). Emitted when battery level reporting is active and percentage calculation is disabled.	Yes
`battery.remainingReports`	Estimated Remaining Reports	Integer	Reports	Projected count of remaining cellular report transmissions based on current battery capacity.	Yes
`features.shock.timestamp`	Shock Event Time	String	ISO 8601	UTC timestamp when peak acceleration was registered. `null` if no shock event occurred.	Yes
`features.shock.counter`	Shock Event Counter	Integer	—	Cumulative count of threshold-exceeding impact events registered during the reporting interval.	Yes
`features.shock.magnitude`	Shock Peak Magnitude	Decimal / Float	mg	Peak resultant acceleration magnitude combining all three axes, measured in milli-G (mg).	Yes
`features.shock.duration`	Shock Duration	Integer	ms	Duration of the peak shock impact in milliseconds.	Yes
`features.shock.magnitudeThreshold`	Magnitude Threshold	Integer	mg	Active acceleration threshold required to record a shock event.	Yes
`features.shock.durationThreshold`	Duration Threshold	Integer	ms	Active minimum duration required to qualify an acceleration spike as a valid shock event.	Yes

Trigger Enumerations

Main Triggers (`trigger.main`)

The primary condition that caused the device to initiate network registration and report delivery:

Activation               # Initial label activation when pulled from packaging
Static                   # Scheduled periodic report during stationary interval
Movement                 # Significant movement detected by accelerometer
StartMovement            # Transition from stationary state to motion
Tampering                # Physical seal loop severed or broken
Shock                    # Impact shock exceeding configured magnitude and duration
TemperatureAlert         # Temperature breached configured lower or upper threshold
TemperatureBackInRange   # Temperature returned within normal operating bounds
HumidityAlert            # Relative humidity breached configured bounds
LightArm                 # Light sensor armed after period of total darkness
LightBreach              # Ambient light detected while label was armed in carton
Takeoff                  # Flight takeoff detected via pressure and cellular disconnect
Landing                  # Flight landing detected; cellular modem re-enabled
RegainNetwork            # Re-established cellular connection after out-of-coverage period

Additional Triggers (`trigger.list`)

Secondary conditions flagged in the same transmission window:

Heartbeat                # Baseline periodic health ping
SavedReport              # Backlogged report stored in flash memory during out-of-coverage

Updated 11 days ago

Did this page help you?