Guides
SUPPORTFEEDBACK

Insuretech

Learn how to integrate Samsara data with insurtech software

Suggest Edits

Samsara provides rich telematics and fleet data. By integrating with these APIs, insurers can automate workflows, gain visibility into fleet operations, and reduce claims costs. Common use cases include:

  • Claims: Rapid First Notice of Loss (FNOL) using real-time safety event data.
  • Underwriting: Dynamically pricing policies using vehicle usage and driving behavior.
  • Risk Management: Tracking key health indicators, coaching driver behaviors, and detecting risky operating zones.

Building blocks

Below are the primary data sets and capabilities to explore when building an insurtech integration with Samsara.

1. Usage data

Mileage traveled, engine hours, and other distance metrics that reflect how much a vehicle is being driven. This can be used to create usage-based insurance models or for premium calculations tied to utilization.

  • obdOdometerMeters - The odometer reading according to onboard diagnostics. If
    Samsara does not have diagnostic coverage for a particular vehicle, the value for
    this stat type will be omitted. A jump in mileage has been observed when
    customers switch between vehicles without properly decoupling and re-enabling a
    gateway for their new vehicle.
  • gpsDistanceMeters - The distance the vehicle has traveled since the gateway was
    installed based on GPS calculations.
  • gpsOdometerMeters - The GPS-reported “odometer” reading as edited by the
    customer and tracked via GPS.

See the Mileage and distance guide for more details.

Example request

curl "https://api.samsara.com/fleet/vehicles/stats/history?vehicleIds=123&types=obdOdometerMeters,gpsOdometerMeters,gpsDistanceMeters&endTime=2025-03-19T11:27:31Z&startTime=2025-03-19T11:25:31Z" \
     --header "Authorization: Bearer <YOUR_API_TOKEN>"

Example response

{
  "data": [
    {
      "id": "123",
      "name": "Truck",
      "externalIds": {
        "samsara.serial": "G122SBGJT9",
        "samsara.vin": "111"
      },
      "obdOdometerMeters": {
        "time": "2025-03-20T12:13:38Z",
        "value": 188982000
      },
      "gpsOdometerMeters": {
        "time": "2025-03-20T16:14:20Z",
        "value": 190111382
      },
      "gpsDistanceMeters": {
        "time": "2025-03-20T16:14:20Z",
        "value": 1810088.2739995187
      }
    }
  ],
  "pagination": {
    "endCursor": "",
    "hasNextPage": false
  }
}

Use obdOdometerMeters where possible, falling back to gpsDistanceMeters if the odometer is not available.

2. Safety events

Use the Safety Events API to fetch data for calculating the following insights:

  • Calculating driver and vehicle safety trends
  • Retrieving safety event videos
  • Coaching trends and statuses
  • First Notice of Loss (FNOL)

Example request

curl -X GET 'https://api.samsara.com/fleet/safety-events?startTime=2024-03-19T00:00:00.000Z&endTime=2025-03-20T00:00:00.000Z' \
--header "Authorization: Bearer <TOKEN>"

Example response

{
    "data": [
        {
            "id": "281474994182986-1742297270973",
            "driver": {
                "id": "52514325",
                "name": "Test Driver"
            },
            "vehicle": {
                "id": "123",
                "name": "Truck",
                "externalIds": {
                    "samsara.serial": "G522SBGJT9",
                    "samsara.vin": "123"
                }
            },
            "time": "2025-03-18T11:27:50.973Z",
            "maxAccelerationGForce": 0,
            "downloadForwardVideoUrl": "https://s3.samsara.com/samsara-cvdata/...",
            "downloadInwardVideoUrl": "https://s3.samsara.com/samsara-dashcam-videos/...",
            "location": {
                "latitude": 42.94652622,
                "longitude": -71.50658407
            },
            "coachingState": "needsReview",
            "behaviorLabels": [
                {
                    "label": "rollingStop",
                    "source": "automated",
                    "name": "Rolling Stop"
                }
            ]
        },        
        {
            "id": "281474994182986-1737721907268",
            "driver": {
                "id": "52514325",
                "name": "Test Driver"
            },
            "vehicle": {
                "id": "123",
                "name": "Truck",
                "externalIds": {
                    "samsara.serial": "G522SBGJT9",
                    "samsara.vin": "123"
                }
            },
            "time": "2025-01-24T12:31:47.268Z",
            "maxAccelerationGForce": 0,
            "downloadForwardVideoUrl": "https://s3.samsara.com/samsara-dashcam-videos/...d",
            "downloadInwardVideoUrl": "https://s3.samsara.com/samsara-dashcam-videos/400...e",
            "location": {
                "latitude": 42.94235388,
                "longitude": -71.50552728
            },
            "coachingState": "needsReview",
            "behaviorLabels": [
                {
                    "label": "mobileUsage",
                    "source": "automated",
                    "name": "Mobile Usage"
                }
            ]
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

Safety event data can be used to build risk scoring models, measure driver improvement, and generate immediate notifications for FNOL.

Safety Trends

Calculate safety trends with the count of events in a time series. The type of event
is denoted in the behaviorLabels.label field of the event data. Here’s a list of common
event types that detected:

  • Harsh Brake
  • Harsh Turn
  • Harsh Acceleration
  • Crash
  • Tailgating
  • Distracted Driving
  • Near Collision
  • No Seatbelt

Users of the platform can create custom labels like “Did Not Yield” and “Smoking”. Check the behaviorLabels.source field for “userGenerated”.

Driver safety and behavior

The driver object will only exist on safety event responses if a driver was assigned to the vehicle during the event or if an administrator of the dashboard manually assigns a driver.

Vehicle safety

All safety events have a vehicle assigned. This data can be used to build trend charts, efficacy models, or event prediction models.

Coaching Status

Calculate coaching metrics including coaching effectiveness, coaching date, and percentage of events coached. The coachingState in the response contains the current status of the harsh event as it works its way through our coaching workflow. Admins can mark events that need coaching or recognition, then can note when those actions have been completed. All events start with the status of “Needs Review”. For insuretech, understanding coaching data signals whether the customer is using this part of the platform, especially if they are a large and/or distributed fleet. Here are the most common coaching status labels that can be set by the customer admin:

  • needsReview
    • Event needs reviewed
    • Default status for all new events
  • reviewed
    • Event has been reviewed
  • needsCoaching
    • Events needs coaching
  • coached
    • Event has been coached
  • dismissed
    • Event has been dismissed as invalid
  • needsRecognition
    • Driver needs to be recognized
  • recognized
    • Driver has been recognized

First Notice of Loss (FNOL)

There are two approaches to determine FNOL.

  1. Safety Events API: using an on-going process that queries the safety-events endpoint, FNOL can be reported within minutes. We recommend that you query with a 30 minute delay, which allows for the event metadata and video to load up to the cloud.
  2. Safety Events Feed API. Filter results by data[n].type == CreateSafetyEventActivityType, so it only returns when new events are created.

Retrieving Safety Event Videos

The API returns download links for up to three videos: forward-facing, driver-facing, and tracked driver-facing. The latter shows the AI-generated bounding box around the driver’s face for distracted driving detection.

3. Vehicle location

Vehicle location data reveals where a fleet spends its time. A fleet’s operating area—down to the street level—can help determine the likelihood of incidents that may lead to claims. Our vehicle location endpoints provide “breadcrumb” data points (latitude, longitude, and timestamp) on a sub-minute basis.

Underwriters can use this to understand operating regions. Claims teams can verify reported locations or reconstruct events.

Use the vehicle stats endpoints to fetch the gps stat type.

Example request

curl --request GET \
     --url 'https://api.samsara.com/fleet/vehicles/stats/history?vehicleIds=123&types=gps&startTime=2025-03-20T11:20:33Z&endTime=2025-03-20T11:21:33Z' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <token>'

Example response

{
  "data": [
    {
      "id": "123",
      "name": "Truck",
      "externalIds": {
        "samsara.serial": "G522SBGJT9",
        "samsara.vin": "123"
      },
      "gps": [
        {
          "time": "2025-03-20T11:20:38.024Z",
          "latitude": 43.94081487,
          "longitude": -76.22608032,
          "headingDegrees": 352.9,
          "speedMilesPerHour": 31.071,
          "reverseGeo": {
            "formattedLocation": "123 Main St, USA, 99999"
          },
          "isEcuSpeed": true
        },
        {
          "time": "2025-03-20T11:20:44.014Z",
          "latitude": 43.941539489,
          "longitude": -76.22626658,
          "headingDegrees": 347.8,
          "speedMilesPerHour": 29.828,
          "reverseGeo": {
            "formattedLocation": "123 Main St, USA, 99999"
          },
          "isEcuSpeed": true
        },
				...
      ]
    }
  ],
  "pagination": {
    "endCursor": "",
    "hasNextPage": false
  }
}

4. Vehicle speed

Real-time or historic speed and heading, as recorded by the Samsara hardware. Useful for verifying driving behaviors, assessing speeding incidents, and modeling risk.

Speed history

To view the granular vehicle speed readings over time, use the Historical stats endpoint with the ecuSpeedMph vehicle stat type.

Example request

curl --request GET \
     --url 'https://api.samsara.com/fleet/vehicles/stats/history?vehicleIds=123&types=ecuSpeedMph&startTime=2025-03-20T11:20:33Z&endTime=2025-03-20T11:21:33Z' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <token>'

Example response

{
  "data": [
    {
      "id": "123",
      "name": "Truck",
      "externalIds": {
        "samsara.serial": "G522SBGJT9",
        "samsara.vin": "123"
      },
      "ecuSpeedMph": [
        {
          "time": "2025-03-20T11:20:34Z",
          "value": 30.4496241946906
        },
        {
          "time": "2025-03-20T11:20:53Z",
          "value": 24.85683607729845
        },
        {
          "time": "2025-03-20T11:21:00Z",
          "value": 4.97136721545969
        },
        {
          "time": "2025-03-20T11:21:01Z",
          "value": 7.457050823189535
        },
        {
          "time": "2025-03-20T11:21:07Z",
          "value": 23.613994273433526
        },
        {
          "time": "2025-03-20T11:21:12Z",
          "value": 32.31388690048798
        }
      ]
    }
  ],
  "pagination": {
    "endCursor": "",
    "hasNextPage": false
  }
}

Speeding intervals

Retrieve a list of speeding intervals related to completed trips, use the Get Speeding Intervals endpoint. Notice that speeding intervals also include the posted speed limit to contrast against the maximum speed for that interval.

Example request

curl --location 'https://api.samsara.com/speeding-intervals/stream?assetIds=281474994182986&startTime=2025-03-25T13%3A56%3A29.005Z&endTime=2025-03-25T14%3A15%3A29.005Z' \
--header 'Accept: application/json' \
--header 'Authorization: <token>'

Example response

{
  "data": [
    {
      "tripStartTime": "2025-03-25T13:48:04.011Z",
      "createdAtTime": "2025-03-25T13:48:46.748Z",
      "updatedAtTime": "2025-03-25T14:12:57.085Z",
      "asset": {
        "id": "123"
      },
      "intervals": [
        {
          "postedSpeedLimitKilometersPerHour": 56,
          "maxSpeedKilometersPerHour": 73.00584,
          "severityLevel": "moderate",
          "startTime": "2025-03-25T13:51:05.006Z",
          "endTime": "2025-03-25T13:52:18.006Z",
          "location": {
            "latitude": 43.93165049,
            "longitude": -72.54512202,
            "headingDegrees": 141,
            "accuracyMeters": 2,
            "address": {
              "streetNumber": "2",
              "pointOfInterest": "",
              "neighborhood": "",
              "street": "Buffer Road",
              "city": "Appleton",
              "state": "CA",
              "postalCode": "99999",
              "country": "US"
            }
          },
          "isDismissed": false
        },
        {
          "postedSpeedLimitKilometersPerHour": 56,
          "maxSpeedKilometersPerHour": 69.00552,
          "severityLevel": "moderate",
          "startTime": "2025-03-25T13:54:03.008Z",
          "endTime": "2025-03-25T13:55:30.001Z",
          "location": {
            "latitude": 43.93165049,
            "longitude": -72.54512202,
            "headingDegrees": 141,
            "accuracyMeters": 2,
            "address": {
              "streetNumber": "2",
              "pointOfInterest": "",
              "neighborhood": "",
              "street": "Buffer Road",
              "city": "Appleton",
              "state": "CA",
              "postalCode": "99999",
              "country": "US"
            }
          },
          "isDismissed": false
        },
        ...
      ]
    }
  ],
  "pagination": {
    "endCursor": "",
    "hasNextPage": false
  }
}

5. Vehicle data

Vehicle details that rarely change (VIN, Year, Make, Model, etc.). Helps you understand fleet composition and track each vehicle over time.

List all vehicles

Example request

curl -X GET 'https://api.samsara.com/fleet/vehicles' \
--header "Authorization: Bearer <TOKEN>"

Example response

{
  "data": [
    {
      "attributes": [
        {
          "id": "f4814238-00c6-4737-9896-8799c988b519",
          "name": "Color",
          "stringValues": [
            "Gray"
          ]
        }
      ],
      "cameraSerial": "G52R-2KJ-APF",
      "externalIds": {
        "samsara.serial": "G522SBGJT9",
        "samsara.vin": "123"
      },
      "gateway": {
        "serial": "G522-SBG-JT9",
        "model": "VG55NA"
      },
      "harshAccelerationSettingType": "lightTruck",
      "id": "123",
      "make": "FORD",
      "model": "F-150",
      "name": "Truck",
      "notes": "test",
      "serial": "G522SBGJT9",
      "staticAssignedDriver": {
        "id": "123",
        "name": "Test Driver"
      },
      "tags": [
        {
          "id": "4857663",
          "name": "Primary"
        }
      ],
      "vin": "123",
      "year": "2016",
      "vehicleRegulationMode": "regulated",
      "createdAtTime": "2025-01-17T20:57:42Z",
      "updatedAtTime": "2025-02-10T16:05:33Z"
    }
  ],
  "pagination": {
    "endCursor": "",
    "hasNextPage": false
  }
}

Fleet Size

Use the List All Vehicles endpoint to get a sense of the general size of the fleet.

6. Vehicle health

Engine fault codes, temperature readings, battery voltage, oil pressure, and other real-time metrics help identify vehicle condition. Risk and underwriting teams can evaluate whether fleets are maintaining safe vehicles.

  • Engine Fault Codes
    • Engine codes reported by the ECU. More information on engine codes is is available in the Fault Monitoring guide.
  • Ambient Air Temperature
    • If equipped with an external thermostat, this stat can be pulled for event reconstruction (e.g. external temperature was below freezing).
  • Vehicle Battery Voltage
  • Diesel Exhaust Fluid (DEF) level
  • Engine Coolant Temperature
  • Engine Immobilizer
    • If the customer is using our engine immobilizer to prevent vehicle thefts, this will
      return if the immobilizer has been engaged or not.
  • Engine Load Percent
  • Engine Oil Pressure
  • Engine RPM
  • Engine States (On, Off, Idle)
  • Fuel Percentage
  • Intake Manifold Temperature
  • Engine Seconds
    • The cumulative number of seconds the engine has run according to onboard
      diagnostics.

Example request

curl "https://api.samsara.com/fleet/vehicles/stats?types=faultCodes,ambientAirTemperatureMilliC,engineLoadPercent&vehicleIds=123&endTime=2025-03-19T11:27:31Z&startTime=2025-03-19T11:25:31Z" \
     --header "Authorization: Bearer <YOUR_API_TOKEN>"

Example response

{
  "data": [
    {
      "id": "123",
      "name": "Truck",
      "externalIds": {
        "samsara.serial": "G522SBGJT9",
        "samsara.vin": "123"
      },
      "faultCodes": {
        "obdii": {
          "diagnosticTroubleCodes": [
            {
              "confirmedDtcs": [],
              "pendingDtcs": [],
              "permanentDtcs": [],
              "monitorStatus": {
                "misfire": "R",
                "fuel": "R",
                "comprehensive": "R",
                "catalyst": "R",
                "heatedCatalyst": "U",
                "evapSystem": "R",
                "secondaryAir": "U",
                "isoSaeReserved": "U",
                "o2Sensor": "R",
                "heatedO2Sensor": "R",
                "egr": "R",
                "notReadyCount": 0
              },
              "txId": 2024,
              "ignitionType": "spark",
              "milStatus": false
            }
          ],
          "checkEngineLightIsOn": false
        },
        "canBusType": "CANBUS_SECONDARY_PASSENGER_15765",
        "time": "2025-03-25T18:44:15Z"
      },
      "ambientAirTemperatureMilliC": {
        "time": "2025-03-25T19:43:23Z",
        "value": 10000
      },
      "engineLoadPercent": {
        "time": "2025-03-25T19:43:23Z",
        "value": 55
      }
    }
  ],
  "pagination": {
    "endCursor": "",
    "hasNextPage": false
  }
}

7. Hours of service (North America)

Electronic Logging Device (ELD) data that tracks driver on-duty, off-duty, and sleeper-berth statuses. Mainly used in North American fleets for regulatory compliance and risk assessment.

Use the HOS logs endpoint to fetch duty status history. 

curl 'https://api.samsara.com/fleet/hos/logs?startTime=2025-03-10T00:00:00Z&endTime=2025-03-25T00:00:00Z' \
  --header "Authorization: Bearer <token>"

Example response

{
  "data": [
    {
      "driver": {
        "id": "555",
        "name": "Test Driver"
      },
      "hosLogs": [
        {
          "codrivers": [],
          "hosStatusType": "onDuty",
          "logEndTime": "2025-03-10T12:10:56.027Z",
          "logRecordedLocation": {
            "latitude": 43.9384319,
            "longitude": -72.533966919
          },
          "logStartTime": "2025-03-10T11:55:00.014Z",
          "vehicle": {
            "id": "123"
          }
        },
        {
          "codrivers": [],
          "hosStatusType": "driving",
          "logEndTime": "2025-03-10T12:19:38.008Z",
          "logRecordedLocation": {
            "latitude": 43.93854583,
            "longitude": -72.53389045
          },
          "logStartTime": "2025-03-10T12:10:56.027Z",
          "vehicle": {
            "id": "123"
          }
        },
        {
          "codrivers": [],
          "hosStatusType": "sleeperBed",
          "logEndTime": "2025-03-11T00:00:00.000Z",
          "logRecordedLocation": {
            "latitude": 43.93845637,
            "longitude": -72.53398559
          },
          "logStartTime": "2025-03-10T12:19:38.008Z",
          "vehicle": {
            "id": "123"
          }
        }
      ]
    }
  ],
  "pagination": {
    "endCursor": "...",
    "hasNextPage": true
  }
}

8. Tachograph data (EU)

Tachograph driver files and vehicle files required for EU compliance. Mirrors the Hours of Service concept, but for EU-based fleets.

Example request

curl 'https://api.samsara.com/fleet/drivers/tachograph-activity/history?startTime=2025-03-10T00%3A00%3A00Z&endTime=2025-03-25T00%3A00%3A00Z' \
     --header 'authorization: Bearer <token>'

Example response

{
  "data": [
    {
      "activity": [
        {
          "endTime": "2020-01-03T16:04:05Z07:00",
          "isManualEntry": false,
          "startTime": "2020-01-02T15:04:05Z07:00",
          "state": "BREAK/REST"
        }
      ],
      "driver": {
        "id": "123",
        "name": "Test Driver"
      }
    }
  ],
  "pagination": {
    "endCursor": "...",
    "hasNextPage": true
  }
}

9. Device installation status

Checking whether a customer has physically installed Samsara Vehicle Gateways. Shows “not installed” until the hardware powers on and reports its first location.

Use the List Gateways API to fetch gateways. The new [beta] List devices. is in beta and will have even more rich device installation and health data.

Example request

curl -X GET 'https://api.samsara.com/gateways' \
--header "Authorization: Bearer <TOKEN>"

Example response

{
  "data": [
    {
      "serial": "G522-SBG-JT9",
      "model": "VG55NA",
      "asset": {
        "id": "123",
        "externalIds": {
          "samsara.serial": "G522SBGJT9",
          "samsara.vin": "123"
        }
      },
      "connectionStatus": {
        "healthStatus": "Connected",
        "lastConnected": "2025-03-20T21:13:26.557Z"
      },
      "dataUsageLast30Days": {
        "cellularDataUsageBytes": 104982628,
        "hotspotUsageBytes": 0
      },
      "accessoryDevices": [
        {
          "serial": "G52R-2KJ-APF",
          "model": "CM34"
        }
      ]
    },
		...,
  ],
  "pagination": {
    "endCursor": "",
    "hasNextPage": false
  }
}

(Optional) Adding an admin user

Programmatically create a read-only administrative account for your team on a customer’s Samsara dashboard (with the correct permissions). This is often needed if you require direct visibility without manually logging into each customer’s account.

First, retrieve the ID for the read-only admin role using the List all user roles endpoint. This role ID is used in the next API call to create the user.

Create a User API

  • Ensure the token used has the Users: Read/Write scope.

Example request

curl --request POST \
     --url https://api.samsara.com/users \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '{
  "authType": "default",
  "email": "[email protected]",
  "name": "Demo Insuretech User",
  "roles": [
    {
      "roleId": "717fe0f3-f87f-4a57-b3ce-33a5a9f394cd"
    }
  ]
}'

Example response

{
  "data": {
    "id": "1220306",
    "name": "Demo Insuretech User",
    "email": "[email protected]",
    "authType": "default",
    "roles": [
      {
        "role": {
          "id": "717fe0f3-f87f-4a57-b3ce-33a5a9f394cd",
          "name": "Read-only Admin"
        }
      }
    ]
  }
}

Next steps

By combining the above building blocks, you can create robust insurance solutions that automate FNOL, enable usage-based policy pricing, and continuously monitor risk. In practice, you will orchestrate several of these APIs to pull data on a regular schedule or in near real-time, run analytics or scoring algorithms, and present insights in your product.

Refer to the Samsara Developer Documentation for in-depth details, examples, and best practices. Always be sure to confirm that your API token has the relevant permissions for each endpoint you plan to call.

Updated about 13 hours ago