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.0,
    "isLightBreached": false,
    "accelerometer": {
      "xAxis": 0,
      "yAxis": 32,
      "zAxis": 976
    }
  },
  "battery": {
    "voltage": 2989,
    "percentage": 87
  },
  "features": {
    "shock": {
      "timestamp": "2026-09-15T12:30:00Z",
      "counter": 2,
      "magnitude": 12400,
      "duration": 40,
      "magnitudeThreshold": 10000,
      "durationThreshold": 80
    }
  }
}

Missing Values

Fields that have no value in a report are omitted from the payload; they are never sent as null. Fields marked Optional: Yes in the table below may therefore be absent. When a report has no location, location is an empty object ({}); when no shock was recorded, features is an empty object ({}).

Data Report Schema Fields

Field Name	Description	Type	Units	Detailed Description	Optional
`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 with whole seconds (`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.	No
`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"`, or `"Wifi"`.	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"`). See Trigger Enumerations.	No
`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).	No
`sensors.light`	Ambient Light	Decimal / Float	Lux	Ambient illumination intensity in lux (calculated as raw sensor ADC × 4). Emitted only 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. Omitted when the light sensor state is unknown or unconfigured.	Yes
`sensors.accelerometer.xAxis`	X-Axis Acceleration	Integer	mg	Instantaneous linear acceleration along the X-axis in milli-G (mg).	No
`sensors.accelerometer.yAxis`	Y-Axis Acceleration	Integer	mg	Instantaneous linear acceleration along the Y-axis in milli-G (mg).	No
`sensors.accelerometer.zAxis`	Z-Axis Acceleration	Integer	mg	Instantaneous linear acceleration along the Z-axis in milli-G (mg).	No
`battery.voltage`	Cell Voltage	Integer	mV	Instantaneous battery terminal voltage in millivolts. Primary indicator of electrical power reserve.	Yes
`battery.percentage`	Battery Percentage	Integer	%	Estimated State of Charge (SoC) from 0% to 100%. Emitted only when battery percentage calculation is enabled for the account.	Yes
`battery.level`	Battery Level Category	String	—	Categorical battery status: `"Full"`, `"High"`, `"Mid"`, or `"Low"`. Emitted only when battery level reporting is enabled for the account and battery percentage calculation is not.	Yes
`features.shock.timestamp`	Shock Event Time	String	ISO 8601	UTC timestamp when peak acceleration was registered.	No (when `features.shock` is present)
`features.shock.counter`	Shock Event Counter	Integer	—	Cumulative count of threshold-exceeding impact events registered during the reporting interval.	No (when `features.shock` is present)
`features.shock.magnitude`	Shock Peak Magnitude	Integer	mg	Peak resultant acceleration magnitude combining all three axes, measured in milli-G (mg).	No (when `features.shock` is present)
`features.shock.duration`	Shock Duration	Integer	ms	Duration of the peak shock impact in milliseconds.	No (when `features.shock` is present)
`features.shock.magnitudeThreshold`	Magnitude Threshold	Integer	mg	Active acceleration threshold required to record a shock event.	No (when `features.shock` is present)
`features.shock.durationThreshold`	Duration Threshold	Integer	ms	Active minimum duration required to qualify an acceleration spike as a valid shock event.	No (when `features.shock` is present)

Trigger Enumerations

trigger.main and the entries of trigger.list use the same set of values. Any of the values below can appear in either field.

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
SealApplied              # Physical seal loop applied (closed)
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
HumidityBackInRange      # Relative humidity returned within 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