Samsara Integration
What actually syncs, how vehicles get matched, and where to look when a reading doesn't show up.
On this page
What this integration does
The Samsara integration pulls one thing from Samsara's Fleet API: distance data for each vehicle. Specifically, it requests two stat types — obdOdometerMeters (the vehicle's OBD-reported odometer) and gpsDistanceMeters (GPS-derived cumulative distance, used as a fallback when a vehicle doesn't report OBD odometer data) — and converts whichever value is present into miles.
That is what the daily meter sync does, and it is the only thing that writes to your meters. Separately, each vehicle's Telematics tab reads live sensor data from Samsara (fuel, battery, tires, fault codes, location) for display and for fault-code work orders — see The vehicle Telematics tab. Engine hours and driver behavior/safety events are not requested.
Setup, step by step
- In Samsara, generate a read-only API token under Settings → API Tokens. No webhook or callback URL needs to be configured on Samsara's side — this integration only ever calls out to Samsara, it never receives anything from Samsara.
- In Equipt, go to Settings → Integrations and paste the token into the API Key field, then click Save.
- For each vehicle you want synced, open its detail page and set the Samsara Vehicle ID field (under Integrations, in the New/Edit Vehicle dialog) — Samsara shows this ID in the URL when you select a vehicle under Fleet → Vehicles. This step is optional but strongly recommended; see vehicle matching below for what happens if you skip it.
- Click Sync Now on the Integrations tab to run a first sync immediately, rather than waiting for the next scheduled run. The button is disabled until an API key has been saved.
How vehicle matching works
Each vehicle Samsara returns is matched to an Equipt vehicle in two passes:
- By Samsara Vehicle ID first — if the vehicle's
samsara_vehicle_idfield matches the ID on the incoming record, that's the match. - By exact name second — if no ID match is found, it falls back to a case-insensitive, trimmed comparison of the vehicle's name against Samsara's vehicle name.
A Samsara vehicle with no match in either pass isn't treated as an error — it's simply skipped, and a line noting the unmatched vehicle name and Samsara ID is added to that sync run's detail log (visible after a manual Sync Now).
Sync mechanics
Sync is triggered two ways, both hitting the same route (/api/integrations/samsara/sync):
| Trigger | How it works |
|---|---|
| Scheduled | A Vercel Cron job hits the route once a day at 10:00 UTC (6:00 AM ET), authenticated with a cron secret. This run syncs every org that has Samsara enabled with a saved API key — not just one org. |
| Manual | Clicking Sync Now on Settings → Integrations sends an authenticated POST as the logged-in user. This requires an admin role — the route checks the caller's profile and rejects non-admins — and only syncs the caller's own org. |
There is no webhook from Samsara and no near-real-time delivery — every reading you see came from one of these two pulls. Samsara's stats endpoint is paginated; the sync follows the pagination cursor until Samsara reports no further pages, so large fleets are fully fetched in one run.
How a reading turns into a meter update
For each matched vehicle, the sync looks for meters on that vehicle with a unit of miles or mi:
- No miles meter exists yet — one is auto-created, named "Odometer," starting at 0, labelled as a Samsara meter and carrying the vehicle's name. You don't need to create a meter by hand before syncing a vehicle for the first time.
- The incoming mileage is less than the meter's current value — the reading is always saved to the meter's history. If the meter's latest reading was entered manually (for example a mistyped, too-high odometer), the Samsara reading replaces it as the current value, so one bad manual entry can't block syncing. If the latest reading already came from Samsara, odometers don't go backwards, so the lower reading is kept in the history with a note but the current value is left alone. Either way the meter's Last Reading time is refreshed.
- The incoming mileage is greater than or equal to the current value — a new row is inserted into
meter_readingswithsource: "samsara"and a note of whether the value came from OBD or GPS. The meter'scurrent_valueis only advanced when the new mileage is strictly greater than what's currently stored — equal readings are still logged (so you have a daily record even with no vehicle movement) but don't re-trigger the meter update.
That current-value update is conditioned on the database row's value at write time, not a value read earlier in the same run — this matters because the cron job and a manual Sync Now could in principle overlap, and this guards against one clobbering a higher value written by the other.
Sync status and errors
After every run, each org's integrations row is stamped with a timestamp and a status, both shown on Settings → Integrations:
| Status | Meaning |
|---|---|
| Connected (ok) | No errors this run. |
| Partial | At least one vehicle matched and got a reading, but at least one error also occurred (e.g. a meter failed to create, a reading failed to insert). |
| Error | No vehicles matched at all, or the call to Samsara's API failed outright — most commonly an invalid or expired API key, which surfaces here as a failed fetch rather than a distinct "bad key" message. |
A manual Sync Now additionally shows the run's full detail log inline — counts of vehicles fetched from Samsara, matched, and readings written, plus a line-by-line list (unmatched vehicles, skipped backwards readings, any insert failures). The scheduled daily run doesn't surface that detail anywhere in the UI — only the summary status and last-synced timestamp update.
Meters and automations
A Samsara-written reading is not a special case for anything downstream — it updates the vehicle's meter through the exact same meter_readings + meters.current_value path a manually logged reading would use, just tagged with source: "samsara" instead of a person's name. That means any meter-threshold automation configured on that meter fires exactly the same way it would from a manual entry — see Building a meter-threshold automation and Pending Reset, explained in the Meters guide for how that firing, Pending Reset, and Service Interval logic works — none of it is re-explained here since it doesn't change based on where the reading came from.
The vehicle Telematics tab
Once an admin has connected Samsara (Settings > Integrations), every vehicle in Equipt > Vehicles gets a Telematics tab. It does not appear while Samsara is not connected. Opening the tab pulls the latest readings from Samsara, and the Refresh button pulls them again.
- Sensor readings: engine state, battery voltage, tire pressure at each corner, fuel level, coolant temperature and DEF level. A reading the vehicle does not report shows Not reported, not zero.
- Location: a map with the vehicle's address, speed and heading.
- History: fuel and battery charts over 7, 30 or 90 days. An hourly job records one sample per vehicle per hour, so a chart starts filling from the first hour after Samsara is connected.
The tab explains why it is empty instead of failing: Samsara isn't connected (an admin adds the API key under Settings > Integrations), This vehicle isn't linked to Samsara (set its Samsara Vehicle ID on the Details tab, or name it exactly as it appears in Samsara, then reopen the tab) or No telematics yet (use Try again).
Fault codes, work orders and automations
The Fault Codes card lists the vehicle's current codes, each marked Confirmed, Pending or Permanent. Pending codes are shown for information only: they flicker on and off while the engine computer decides whether a fault is real, so they never raise work. A confirmed or permanent code can become a work order in two ways.
- By hand: click Create work order beside the code (you need permission to edit work orders). The work order carries the code, its description and the check-engine-light state, and is high priority when the light is on. Once raised, the work order number replaces the button and links to it. Clicking again for the same open code returns the existing work order instead of making a second one.
- Automatically: in Equipt > Automations choose the Vehicle Fault Code trigger. It fires once when a connected vehicle reports a new confirmed fault code, and can be limited to Only when the check-engine light is on. Its actions (create a work order, a request or a notification) include the code and description.
The first hourly check after Samsara is connected records the codes a vehicle already has without firing automations, so switching the feature on does not create a burst of work orders. Only codes that appear after that fire. When a code stops being reported it is cleared; if it comes back later it counts as a new occurrence.