Connecting Samsara, Fleetio and other services
Keys are entered in Admin > System settings > Connections (administrators). They are saved on the server and never shown again: the screen shows only whether a key is set and when it was changed.
To copy all of a company's data from Fleetio, Samsara, Motive or Geotab into this server (once, or kept in sync), see Copy from other platforms.
Samsara (telematics) #
- What it provides: positions, speed, engine data and faults, hours of service, driver inspections (DVIRs), safety events and camera stills.
- Direction: read only, from Samsara into Fleet OverWatch, every few seconds.
- Token: create an API token in Samsara (Settings > API Tokens) with read access to vehicles, drivers, locations, ELD/HOS, safety and camera media, and paste it.
- Matching: live units join vehicle records by VIN, name, or the record's Samsara vehicle id field.
Fleetio (optional) #
Fleet OverWatch keeps its own maintenance records. A Fleetio API key and account token let you bring Fleetio records over once, or keep syncing for a while (Maintenance > Integrations > Fleetio). You can also import Fleetio's CSV exports.
Comdata fuel cards #
Where: Maintenance › Integrations › Comdata fuel cards. Who: administrators change the settings; administrators, managers and finance upload reports and place transactions.
Comdata card transactions become fuel entries on the right truck. Each entry gets:
- gallons, price and total;
- the station, city and state (for the IFTA report);
- the odometer and the driver;
- the card's last 4 digits.
Other purchases (oil, parts, scale tickets, washes, cash) can become expenses (tick Add other purchases as expenses). Each transaction is added once, however many times it arrives. Full card numbers are never stored.
There are three ways in:
- Upload a report. In Comdata iConnectData, export a transaction report as CSV, then select Upload Comdata report (CSV). Common column names are recognized: Transaction Date, Unit Number, Driver Name, Card Number, Truck Stop Name / City / State, Product, Number of Gallons, Price Per Gallon, Total Amount Due, Odometer, Transaction Number.
- The Comdata API. You need API access from Comdata, and your Comdata account manager gives the addresses and credentials. Under API settings:
- the API address;
- the sign-in: an OAuth client id and secret (with the token address), an API key, or a user name and password;
- your account / customer code;
- the transactions address and the names of its date parameters.
Tick Poll the Comdata API and select Save. The server checks every 60 minutes (you can change this), looking a few days back each time. Poll now checks at once.
- Pushed to us. Comdata or another program can send transactions to the address shown, as JSON or CSV.
How trucks are found: by the Comdata unit number (the vehicle's name, its plate, or its unit id), otherwise by the truck assigned to the driver. A transaction whose unit matches no truck waits for a vehicle. Select Choose their vehicles, pick the truck and select Add. With Remember, the unit number is saved on the truck: its later transactions, and any others waiting with the same unit, go there by themselves.
Expected result: the fuel entries are on each truck's Fuel tab, in Fuel and costs, MPG and the IFTA report. The card's line shows when it last ran and what it added.
TomTom, maps and weather #
A TomTom key adds live traffic, incidents and truck-aware routing and ETAs. Without it, routing uses OpenStreetMap and estimates. Weather alerts come from the US National Weather Service (no key).
Heavy Labor Project and NHTSA VIN data #
- VIN decoding uses the local NHTSA vPIC database when installed (Local VIN database), otherwise NHTSA's public web service if allowed.
- Labor times (Heavy Labor Project) appear on work orders when a key is configured; without a key the lookups show as not configured.
Other software #
- REST API (
v1.php) with tokens (Maintenance > Integrations > API tokens, orworker.php token). - Outgoing webhooks: a signed POST to your URL when records change.
- Inbound webhook (
hook.php) and feed polling for partner systems.
Test the connections #
Admin > System settings > Connections has Check now; Admin > Health checks lists each integration's status; on the server, worker.php test.
Rate limits and failures #
| What you see | Meaning | What to do |
|---|---|---|
| Samsara HTTP 401 | token wrong or revoked | create a new token and Replace it |
| Samsara HTTP 403 or "check the token's read scope" | the token lacks a permission | add the scope named in the message |
| HTTP 429 | the provider is limiting requests | nothing: the worker backs off and retries |
| Data older than a few minutes | worker stopped or network blocked | worker.php status and test |
Data integration log (4.4.5) #
Admin › Data integration log shows, after every Fleetio sync, how many records of each kind were read from Fleetio, saved, failed, not saved, left out on purpose and are here in total. Every problem is listed with its reason and Fleetio's own record.
- Select a problem to see the reason and the record as Fleetio sent it.
- Put the cause right — for example copy the vehicle it belongs to, or give the API key access to that list in Fleetio.
- Select Retry (or Retry all shown). Expected result: the record is saved and the problem is resolved. A problem also closes by itself when the record saves on a later sync.
Resolve and Ignore keep a note of what was done; Export downloads the log. Every Fleetio record is also kept in full: open a record and select Fleetio data.
Something here out of date or unclear? Tell your administrator and mention “integrations” and version 4.9.2.