Samsara · Schema

Samsara Safety Event

Schema for a Samsara driver safety event as returned by the Samsara Safety API. Represents a detected driving behavior event such as harsh braking, harsh acceleration, harsh cornering, speeding, or camera-detected event.

Asset TrackingConnected OperationsELDFleet ManagementGPS TrackingIoTLogisticsSafetyTelematicsTransportation

Properties

Name	Type	Description
id	string	Unique identifier for the safety event.
eventType	string	Type of safety event detected.
time	string	Timestamp of the safety event in RFC 3339 format.
driver	object	The driver involved in the safety event.
vehicle	object	The vehicle involved in the safety event.
location	object	GPS location where the event occurred.
speedMilesPerHour	number	Vehicle speed in miles per hour at the time of the event.
severity	string	Severity level of the safety event.
coachingState	string	Current coaching workflow state for this event.

View JSON Schema on GitHub

JSON Schema

{
  "$id": "samsara-safety-event-schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Samsara Safety Event",
  "description": "Schema for a Samsara driver safety event as returned by the Samsara Safety API. Represents a detected driving behavior event such as harsh braking, harsh acceleration, harsh cornering, speeding, or camera-detected event.",
  "type": "object",
  "required": ["id", "eventType", "time"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the safety event."
    },
    "eventType": {
      "type": "string",
      "description": "Type of safety event detected.",
      "enum": [
        "crashThresholdExceeded",
        "eatingDriving",
        "drowsyDriving",
        "followingDistanceSevere",
        "followingDistanceModerate",
        "handsOffWheel",
        "harshAccel",
        "harshBrake",
        "harshTurn",
        "inattentiveDriving",
        "landDeparture",
        "mobileUsage",
        "obstructedCamera",
        "rollingStopSign",
        "smokingCigarette",
        "speeding",
        "stopSignViolation",
        "tailgating",
        "yawning"
      ]
    },
    "time": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of the safety event in RFC 3339 format."
    },
    "driver": {
      "type": "object",
      "description": "The driver involved in the safety event.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Driver ID."
        },
        "name": {
          "type": "string",
          "description": "Driver name."
        }
      }
    },
    "vehicle": {
      "type": "object",
      "description": "The vehicle involved in the safety event.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Vehicle ID."
        },
        "name": {
          "type": "string",
          "description": "Vehicle name."
        }
      }
    },
    "location": {
      "type": "object",
      "description": "GPS location where the event occurred.",
      "properties": {
        "latitude": {
          "type": "number",
          "description": "Latitude in decimal degrees.",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "description": "Longitude in decimal degrees.",
          "minimum": -180,
          "maximum": 180
        },
        "formattedAddress": {
          "type": "string",
          "description": "Human-readable address of the event location."
        }
      }
    },
    "speedMilesPerHour": {
      "type": "number",
      "description": "Vehicle speed in miles per hour at the time of the event.",
      "minimum": 0
    },
    "severity": {
      "type": "string",
      "description": "Severity level of the safety event.",
      "enum": ["low", "medium", "high", "critical"]
    },
    "coachingState": {
      "type": "string",
      "description": "Current coaching workflow state for this event.",
      "enum": ["needs_review", "dismissed", "coached", "pending_coach_review"]
    }
  },
  "additionalProperties": true
}