Documentation Index
Fetch the complete documentation index at: https://samsara-showcase.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Core resource events
Event-based Kafka messages are produced when core resources change.
Address
Address Created
{
"eventId": "017db07f-6e95-470e-8cc0-a371f9deed2b",
"eventTime": "1970-01-20T06:39:05.683Z",
"eventType": "AddressCreated",
"orgId": 20936,
"webhookId": "1411751028848270",
"data": {
"address": {
"addressTypes": ["yard"],
"contacts": [
{ "firstName": "Michael", "id": "312312", "lastName": "Johnson" }
],
"createdAtTime": "2021-08-30T19:36:05+00:00",
"externalIds": { "siteId": "54" },
"formattedAddress": "298 Burnley St",
"geofence": {
"circle": {
"latitude": 37.7749,
"longitude": 137.7749,
"radiusMeters": 23
}
},
"id": "494123",
"latitude": 37.7749,
"longitude": 122.4194,
"name": "Company Office #1",
"notes": "This address is located at site 892.",
"tags": [{ "id": "3914", "name": "East Coast", "parentTagId": "4815" }]
}
}
}
{
"eventId": "017db07f-6e95-470e-8cc0-a371f9deed2b",
"eventTime": "1970-01-20T06:39:05.683Z",
"eventType": "AddressDeleted",
"orgId": 20936,
"webhookId": "1411751028848270",
"data": {
"address": {
"externalIds": { "siteId": "54" },
"id": "494123",
"name": "Company Office #1"
}
}
}
{
"eventId": "017db07f-6e95-470e-8cc0-a371f9deed2b",
"eventTime": "1970-01-20T06:39:05.683Z",
"eventType": "AddressUpdated",
"orgId": 20936,
"webhookId": "1411751028848270",
"data": {
"address": {
"addressTypes": ["yard"],
"createdAtTime": "2021-08-30T19:36:05+00:00",
"externalIds": { "siteId": "54" },
"formattedAddress": "298 Burnley St",
"id": "494123",
"latitude": 37.7749,
"longitude": 122.4194,
"name": "Company Office #1",
"notes": "This address is located at site 892."
}
}
}
Driver
Driver Document Submitted
{
"document": {
"createdAtTime": "2024-08-28T19:29:45.000Z",
"documentType": {
"id": "2c541bb5-d033-4a8e-9d53-f3db85d366ff",
"name": "Bill of Lading"
},
"driver": { "id": "51732619", "name": "test driver" },
"fields": [
{ "label": "Photos", "type": "photo", "value": {} },
{ "label": "Reference #", "type": "string", "value": {} }
],
"id": "51732619_1724873385298",
"state": "submitted",
"updatedAtTime": "2024-08-28T19:29:45.000Z",
"vehicle": {
"externalIds": { "samsara.serial": "G7E5GM59H7" },
"id": "281474991565165",
"name": "Test G7E5-GM5-9H7"
}
},
"eventType": "documentSubmitted"
}
{
"driver": {
"carrierSettings": {},
"createdAtTime": "2024-08-28T18:56:08.388Z",
"driverActivationStatus": "active",
"id": "51899168",
"name": "test streaming driver",
"timezone": "America/Los_Angeles",
"updatedAtTime": "2024-08-28T18:56:08.388Z",
"username": "teststreamingdriver"
},
"eventType": "driverCreated"
}
{
"driver": {
"carrierSettings": {},
"createdAtTime": "2024-08-28T18:56:08.388Z",
"driverActivationStatus": "active",
"id": "51899168",
"name": "test streaming driver updated",
"timezone": "America/Los_Angeles",
"updatedAtTime": "2024-08-28T18:56:57.609Z",
"username": "teststreamingdriver"
},
"eventType": "driverUpdated"
}
{
"eventType": "formSubmitted",
"form": {
"createdAtTime": "2024-08-28T18:54:20Z",
"fields": [
{
"id": "7dfc8ba4-47ca-48ff-8793-f4b41de8096b",
"label": "submit forms?",
"multipleChoiceValue": { "value": "Yes" },
"note": "Test",
"type": "multiple_choice"
}
],
"formTemplate": {
"id": "b3a18c2f-1a6b-402c-96c1-bdb764611c40",
"revisionId": "39140122-2f3a-49a5-b5cb-d5cb7e6a1423"
},
"id": "f1e68f82-76f5-4303-869c-45a37c8e6f4d",
"location": {
"latitude": 42.11847729042255,
"longitude": -87.93395625558578
},
"submittedAtTime": "2024-08-28T18:54:20Z",
"submittedBy": { "id": "51732619", "type": "driver" },
"updatedAtTime": "2024-08-28T18:54:20Z"
}
}
Maintenance
DVIR Submitted
{
"dvir": {
"authorSignature": {
"signatoryUser": { "id": "51732619", "name": "test driver" },
"signedAtTime": "2024-08-28T18:52:49.000Z",
"type": "driver"
},
"driver": { "id": "51732619", "name": "test driver" },
"endTime": "2024-08-28T18:52:49.000Z",
"formattedLocation": "Vancouver – Blaine Highway, Surrey, BC, V3S 9N7",
"hasDefects": false,
"id": "624372548",
"needsCorrection": false,
"safetyStatus": "safe",
"startTime": "2024-08-28T18:52:42.086Z",
"type": "postTrip",
"vehicle": {
"externalIds": { "samsara.serial": "G7E5GM59H7" },
"id": "281474991565165",
"licensePlate": "09999",
"name": "Test G7E5-GM5-9H7"
}
},
"eventType": "dvirSubmitted"
}
Contact your Samsara account representative to enable this event for your organization.
{
"eventType": "engineFaultOn",
"fault": {
"j1939": {
"fmi": { "description": "Low—most severe", "id": "1" },
"occurrenceCount": 50,
"spn": {
"description": "Aux Valve 0 Retract Port Measured Flow",
"id": "1900"
},
"txId": "21"
}
},
"vehicle": {
"externalIds": {
"samsara.serial": "GYWYJ42G8E",
"samsara.vin": "3ALACWFC5NDNB5090"
},
"id": "281474991840886",
"name": "GYWY-J42-G8E"
}
}
Contact your Samsara account representative to enable this event for your organization.
{
"eventType": "engineFaultOff",
"fault": {
"j1939": {
"lamps": { "emissions": true }
}
},
"vehicle": {
"externalIds": {
"samsara.serial": "GYWYJ42G8E",
"samsara.vin": "3ALACWFC5NDNB5090"
},
"id": "281474991840886",
"name": "GYWY-J42-G8E"
}
}
Location and Movement
Geofence Entry
{
"address": {
"formattedAddress": "I-5, Blaine, WA, USA",
"geofence": {
"circle": {
"latitude": 48.99867107485855,
"longitude": -122.75289223295576,
"radiusMeters": 322
}
},
"id": "170886751",
"name": "test Geofence"
},
"eventType": "geofenceEntry",
"vehicle": {
"assetType": "vehicle",
"externalIds": { "samsara.serial": "G7E5GM59H7" },
"id": "281474991565165",
"licensePlate": "09999",
"name": "Test G7E5-GM5-9H7"
}
}
{
"address": {
"formattedAddress": "I-5, Blaine, WA, USA",
"geofence": {
"circle": {
"latitude": 48.99867107485855,
"longitude": -122.75289223295576,
"radiusMeters": 322
}
},
"id": "170886751",
"name": "test Geofence"
},
"eventType": "geofenceExit",
"vehicle": {
"assetType": "vehicle",
"externalIds": { "samsara.serial": "G7E5GM59H7" },
"id": "281474991565165",
"licensePlate": "09999",
"name": "Test G7E5-GM5-9H7"
}
}
Routing
Route Stop Arrival
{
"driver": { "id": "51732619", "name": "test driver" },
"eventType": "routeStopArrival",
"operation": "stop departed",
"route": {
"actualRouteEndTime": "2024-08-28T18:48:36.400Z",
"actualRouteStartTime": "2024-08-28T18:47:02.593Z",
"id": "6009862266",
"name": "test route",
"scheduledRouteEndTime": "2024-08-28T18:55:00.000Z",
"scheduledRouteStartTime": "2024-08-28T18:47:00.000Z",
"settings": {
"routeCompletionCondition": "arriveLastStop",
"routeStartingCondition": "departFirstStop"
},
"stops": [
{
"actualArrivalTime": "2024-08-28T18:47:02.593Z",
"actualDepartureTime": "2024-08-28T18:47:02.593Z",
"id": "6066522712",
"name": "Wheeling, IL, USA",
"scheduledDepartureTime": "2024-08-28T18:47:00.000Z",
"state": "departed"
}
]
},
"time": "2024-08-28T18:48:36.400Z",
"type": "route tracking"
}
{
"driver": { "id": "51732619", "name": "test driver" },
"eventType": "routeStopDeparture",
"operation": "stop departed",
"route": {
"actualRouteStartTime": "2024-08-28T18:47:02.593Z",
"id": "6009862266",
"name": "test route"
},
"time": "2024-08-28T18:47:02.593Z",
"type": "route tracking"
}
Safety
Severe Speeding Started
{
"data": {
"startTime": "2024-08-23T17:25:53.101Z",
"tripStartTime": "2024-08-23T17:25:53.101Z",
"vehicle": { "id": "281474991565165" }
},
"eventType": "severeSpeedingStarted"
}
{
"data": {
"endTime": "2024-08-28T18:37:52.834Z",
"startTime": "2024-08-28T18:36:07.713Z",
"tripStartTime": "2024-08-28T18:35:52.027Z",
"vehicle": { "id": "281474991565165" }
},
"eventType": "severeSpeedingEnded"
}
Vehicle
Vehicle Created
{
"eventId": "017db07f-6e95-470e-8cc0-a371f9deed2b",
"eventTime": "1970-01-20T06:39:05.683Z",
"eventType": "VehicleCreated",
"orgId": 20936,
"webhookId": "1411751028848270",
"data": {
"vehicle": {
"assetType": "vehicle",
"externalIds": { "maintenanceId": "250020" },
"gateway": { "serial": "GFRV-43N-VGX" },
"id": "494123",
"licensePlate": "6SAM123",
"name": "Fleet Truck #1",
"vehicleVin": "1GBJ6P1B2HV112765"
}
}
}
{
"eventType": "vehicleUpdated",
"vehicle": {
"createdAtTime": "",
"externalIds": { "samsara.serial": "G7E5GM59H7" },
"gateway": { "model": "VG54NA", "serial": "G7E5-GM5-9H7" },
"harshAccelerationSettingType": "automatic",
"id": "281474991565165",
"licensePlate": "09999",
"name": "Test G7E5-GM5-9H7",
"staticAssignedDriver": { "id": "51732619", "name": "test driver" },
"vehicleRegulationMode": "regulated"
}
}
Ridership
Ridership Kafka messages are produced when ridership actions occur on a route, such as passenger boarding, drop-off, absence marking, undo operations, and unrecognized RFID scans.
Passenger Onboard
Produced when one or more passengers board a vehicle on a ridership route.
{
"eventType": "passengerOnboard",
"eventId": "0193f8a4-7e1c-7000-8000-000000000001",
"occurredAt": "2026-04-15T14:30:00Z",
"createdAt": "2026-04-15T14:30:02Z",
"route": {
"id": "98765",
"externalIds": { "customer.runTemplateId": "28042464" }
},
"actualStop": {
"id": "54321",
"externalIds": { "customer.stopTemplateId": "508166310" }
},
"passengers": [
{
"id": "0193f8a4-0000-7000-8000-000000000100",
"firstName": "Jane",
"lastName": "Doe",
"classification": "Grade 3",
"specialInstructions": {
"specialEducation": false,
"guardianRequired": true
},
"externalIds": { "customer.studentId": "STU-2046" },
"plannedStop": {
"id": "54321",
"externalIds": { "customer.stopTemplateId": "508166310" }
},
"boardingMethod": "rfid",
"rfidTagValue": "E00401007B3E1726"
}
],
"anonymousPassengersCount": 0,
"isBulk": false,
"accountId": "acc-5001"
}
Reference
| Property Name | Type | Description |
|---|
| eventType | string | Always "passengerOnboard". |
| eventId | string | Unique identifier for this event. |
| occurredAt | string | RFC 3339 timestamp of when the boarding occurred. |
| createdAt | string | RFC 3339 timestamp of when the event was created in the system. |
| route | object | The ridership route on which this event occurred. |
| route.id | string | ID of the route. |
| route.externalIds | object | A map of external IDs associated with the route. |
| actualStop | object | The stop where the boarding occurred. |
| actualStop.id | string | ID of the stop. |
| actualStop.externalIds | object | A map of external IDs associated with the stop. |
| passengers | array | List of passengers who boarded. |
| passengers[].id | string | ID of the passenger. |
| passengers[].firstName | string | First name of the passenger. |
| passengers[].lastName | string | Last name of the passenger. |
| passengers[].classification | string | Classification label (e.g., grade level). |
| passengers[].specialInstructions | object | Special instructions for this passenger. |
| passengers[].externalIds | object | External IDs associated with the passenger. |
| passengers[].plannedStop | object | The originally planned boarding stop. |
| passengers[].boardingMethod | string | How the passenger boarded ("rfid", "manual"). |
| passengers[].rfidTagValue | string | The RFID tag value used for boarding, if applicable. |
| anonymousPassengersCount | integer | Number of anonymous passengers who boarded. |
| isBulk | boolean | Whether this was a bulk boarding operation. |
| operationId | string | Identifier linking related events in a bulk operation. |
| accountId | string | ID of the ridership account associated with this event. |
Passenger Drop Off
Produced when one or more passengers are dropped off from a vehicle on a ridership route.
{
"eventType": "passengerDropOff",
"eventId": "0193f8a4-7e1c-7000-8000-000000000001",
"occurredAt": "2026-04-15T15:05:00Z",
"createdAt": "2026-04-15T15:05:01Z",
"route": { "id": "98765" },
"actualStop": { "id": "54322" },
"passengers": [
{
"id": "0193f8a4-0000-7000-8000-000000000100",
"firstName": "Jane",
"lastName": "Doe",
"dropOffMethod": "rfid",
"rfidTagValue": "E00401007B3E1726"
}
],
"anonymousPassengersCount": 0,
"isBulk": false,
"accountId": "ee4c3c26-0cc9-41a4-906d-d1d5d39c2629"
}
Passenger Marked Absent
Produced when one or more passengers are marked as absent on a ridership route.
This event type does not include anonymousPassengersCount.
{
"eventType": "passengerMarkedAbsent",
"eventId": "0193f8a4-7e1c-7000-8000-000000000005",
"occurredAt": "2026-04-15T14:35:00Z",
"createdAt": "2026-04-15T14:35:01Z",
"route": { "id": "98765" },
"actualStop": { "id": "54321" },
"passengers": [
{
"id": "0193f8a4-0000-7000-8000-000000000100",
"firstName": "Jane",
"lastName": "Doe",
"boardingMethod": "rfid",
"rfidTagValue": "E00401007B3E1726"
}
],
"isBulk": false,
"accountId": "ee4c3c26-0cc9-41a4-906d-d1d5d39c2629"
}
Passenger Onboard Undo
Produced when a previous passenger boarding is undone (reversed).
{
"eventType": "passengerOnboardUndo",
"eventId": "evt-m3n4o5p6",
"occurredAt": "2026-04-15T14:32:00Z",
"createdAt": "2026-04-15T14:32:01Z",
"route": { "id": "98765" },
"actualStop": { "id": "54321" },
"passengers": [
{
"id": "0193f8a4-0000-7000-8000-000000000100",
"firstName": "Jane",
"lastName": "Doe",
"boardingMethod": "rfid",
"rfidTagValue": "E00401007B3E1726"
}
],
"anonymousPassengersCount": 0,
"isBulk": false,
"originalEventId": "0193f8a4-7e1c-7000-8000-000000000001",
"accountId": "ee4c3c26-0cc9-41a4-906d-d1d5d39c2629"
}
Passenger Drop Off Undo
Produced when a previous passenger drop-off is undone (reversed).
{
"eventType": "passengerDropOffUndo",
"eventId": "0193f8a4-7e1c-7000-8000-000000000011",
"occurredAt": "2026-04-15T15:10:00Z",
"createdAt": "2026-04-15T15:10:01Z",
"route": { "id": "98765" },
"actualStop": { "id": "54321" },
"passengers": [
{
"id": "0193f8a4-0000-7000-8000-000000000100",
"firstName": "Jane",
"lastName": "Doe",
"dropOffMethod": "rfid",
"rfidTagValue": "E00401007B3E1726"
}
],
"anonymousPassengersCount": 0,
"isBulk": false,
"originalEventId": "0193f8a4-7e1c-7000-8000-000000000002",
"accountId": "ee4c3c26-0cc9-41a4-906d-d1d5d39c2629"
}
Unrecognized RFID Scan
Produced when an RFID tag is scanned but does not match any known passenger in the system.
This event type does not include passengers, anonymousPassengersCount, or isBulk fields.
{
"eventType": "unrecognizedRfidScan",
"eventId": "0193f8a4-7e1c-7000-8000-000000000020",
"occurredAt": "2026-04-15T14:31:00Z",
"createdAt": "2026-04-15T14:31:01Z",
"route": {
"id": "98765",
"externalIds": { "customer.runTemplateId": "28042464" }
},
"actualStop": {
"id": "54321",
"externalIds": { "customer.stopTemplateId": "508166310" }
},
"rfidTagValue": "E00401007BUNKNOWN",
"accountId": "ee4c3c26-0cc9-41a4-906d-d1d5d39c2629"
}
Notes
Kafka Partition Key
All ridership events use the route ID as the Kafka partition key. This ensures that events for the same route are delivered to the same partition and arrive in order.
Field Presence
Fields shown in bold in the reference tables are always present. Non-bold fields are conditional and will be omitted from the payload when they have no value (empty string, zero, or nil).
External IDs
The externalIds fields on route, actualStop, plannedStop, and passengers are maps of key-value string pairs. These represent customer-configured external identifiers that link Samsara entities to external systems. They are only present when the entity has external IDs configured.
Timestamps
All timestamps (occurredAt, createdAt) are in RFC 3339 format (e.g., "2026-04-15T14:30:00Z").
Driver Compliance
This event type is not available by default and requires approval. Reach out to Samsara to request access.
{
"clocks": {
"break": { "timeUntilBreakDurationMs": 28800000 },
"cycle": {
"cycleRemainingDurationMs": 252000000,
"cycleStartedAtTime": "2020-01-27T07:06:25Z",
"cycleTomorrowDurationMs": 252000000
},
"drive": { "driveRemainingDurationMs": 39600000 },
"shift": { "shiftRemainingDurationMs": 50400000 }
},
"currentDutyStatus": { "hosStatusType": "offDuty" },
"currentVehicle": {
"ExternalIds": {
"maintenanceId": "250020",
"payrollId": "ABFS18600"
},
"id": "123456789",
"name": "Midwest Truck #4"
},
"driver": { "id": "88668", "name": "Susan Bob" },
"timestamp": "2025-02-07T17:42:01.740Z",
"violations": {
"cycleViolationDurationMs": 39600000,
"shiftDrivingViolationDurationMs": 39600000
}
}
- Timestamp: exact time (in UTC — reference) when the HOS clocks snapshot was taken for this driver.
