Practical evaluation guide · Updated 7 September 2026
In this guide
Create a read-only vehicle statistics token
In Samsara, create a token with Read Vehicle Statistics permission. Save it in PreventiveHQ Integrations. Tokens are encrypted on the server and are not returned to the browser. Replacing a token clears existing mappings so a new vendor account cannot silently update previously mapped assets.
Map vehicles explicitly
Choose an existing PreventiveHQ asset and enter the Samsara vehicle ID. Select ECU odometer, GPS odometer estimate, ECU engine runtime or estimated runtime. Odometers map to kilometres or miles; runtime maps to hours. Each vehicle maps to one asset per connection. Select the estimate only when it is appropriate for your equipment.
AI-generated editorial illustration; not a customer photograph or product screenshot.
Import the latest available reading
The connector uses Samsara’s vehicle-statistics snapshot endpoint with pagination. It converts metres or seconds to the configured asset unit. Missing, already imported or lower readings are skipped. Retired assets, inactive sites, incompatible units and malformed readings require review rather than silently changing a meter.
Keep maintenance scheduling separate from dispatch
Use the updated asset meter with the existing meter-based maintenance plans. Enabled connections are polled every fifteen minutes when the workspace has active access; the existing maintenance scheduler generates due work. This connector imports maintenance usage readings, not live route maps, driver safety events or fuel-card transactions.
Control and troubleshoot the connection
Use Import latest readings to run a sync and review imported/skipped counts. Automatic failures appear on the connection. Remove a mapping to stop updates to that asset, or disconnect to remove locally stored credentials. Revoke the token in Samsara when it should no longer be usable.
Use telematics data to support a specific maintenance decision
The useful question for a maintenance integration is not simply whether two products can connect. It is which operational decision becomes more reliable when a particular value moves between them. For a fleet team, a current odometer or engine-runtime reading can help determine when usage-based service is due. That is the purpose of this connector: bring selected Samsara vehicle statistics into the asset meter used by PreventiveHQ maintenance plans.
AI-generated editorial illustration; not a customer photograph or product screenshot.
The connection does not replace Samsara’s wider fleet platform. Dispatch, live route views, driver safety, fuel-card transactions and electronic vehicle inspection workflows are outside this connector’s scope. A team can continue using its fleet tools while managing maintenance execution in PreventiveHQ, provided it agrees which system owns each part of the workflow.
Define the first use case narrowly enough to test. For example, select a small group of vehicles whose approved service interval is based on distance, identify their current asset records and confirm the odometer source. A successful pilot should show that the correct reading reaches the correct asset in the correct unit and that the existing maintenance process uses it as intended.
Consult the Samsara vehicle-statistics reference for the provider endpoint and the PreventiveHQ meter-based maintenance guide for the downstream scheduling workflow. The steps below describe this connector’s implemented behavior and operating limits.
Prepare both sides before entering credentials
In PreventiveHQ, create or verify the asset records that will receive readings. Each mapped asset needs an appropriate meter type. Distance statistics require kilometres or miles; engine runtime requires hours. Confirm the asset’s current meter value and the identity of the physical vehicle before adding a mapping.
In Samsara, identify the vehicle ID for each source vehicle and determine which supported statistic is available and appropriate. A vehicle display name can change, and similar names can refer to different units. Use the provider identifier and a reviewed crosswalk to avoid mapping by visual resemblance alone.
Assign an integration owner who can access both the maintenance process and the provider account administration. That person does not need to perform every service, but should know who will review connection errors, stale readings and equipment replacements. An unattended connection with an expired or revoked credential can leave maintenance planning dependent on old values.
Keep a baseline record for the pilot: vehicle identifier, destination asset code, selected metric, unit, current reading and observation time. This makes the first synchronization auditable. It also helps distinguish a conversion problem from an existing disagreement between the provider’s statistic and the manually recorded asset meter.
Create and store the read-only token
Create a Samsara API token with permission to read vehicle statistics. Use a credential dedicated to this integration where your account administration supports that practice, and follow the provider’s current permission interface. Do not place the token in a spreadsheet, work-order note or support screenshot. Enter it through PreventiveHQ Integrations.
PreventiveHQ encrypts stored connection credentials on the server and does not return saved token values to the browser. This reduces unnecessary exposure in the interface, but the organization still needs to manage who can administer the provider account and revoke credentials when appropriate. Encryption does not make an overbroad or publicly shared token a good operational choice.
Replacing the Samsara token clears existing mappings. That behavior is intentional: a new credential could point to a different vendor account, and old asset mappings should not silently continue against that account. After replacement, rebuild and verify the mappings before expecting readings to resume.
If authorization fails, check the token’s permissions and account context through Samsara rather than repeatedly pasting credentials into unrelated fields. A token that can access another provider feature may still lack the statistic permission needed here. Keep troubleshooting focused on the read-only maintenance use case.
Choose the statistic that matches your service policy
The connector supports four selected vehicle statistics. ECU odometer and GPS odometer estimate are distance sources. ECU engine runtime and estimated runtime are time sources. These alternatives should not be treated as interchangeable merely because they produce numbers that increase over time.
AI-generated editorial illustration; not a customer photograph or product screenshot.
| Selected source | Destination meter | Main review question |
|---|---|---|
| ECU odometer | Kilometres or miles | Does this represent the vehicle reading used for service? |
| GPS odometer estimate | Kilometres or miles | Is an estimated distance appropriate for this maintenance policy? |
| ECU engine runtime | Hours | Is engine operating time the approved trigger? |
| Estimated runtime | Hours | Is the estimate suitable and understood by the team? |
Choose one source deliberately for the mapped vehicle and asset. Do not switch between ECU and estimated statistics just to obtain a larger or more recent-looking value. Different sources can have different histories or availability. A source change deserves a baseline comparison and a review of the next maintenance threshold.
For equipment whose maintenance depends on another measurement, such as cycles or a separate component counter, this vehicle-statistics connector is not a substitute for that measurement. Use the appropriate asset process and avoid claiming that every maintenance meter can be populated from these four provider fields.
Map vehicle identities explicitly
Select an existing PreventiveHQ asset and enter its Samsara vehicle ID. Choose the supported metric that should update the asset meter. Each vehicle maps to one asset per connection. Review the mapping with someone who can recognize the vehicle and its service records, particularly when the fleet has similar registration numbers or naming conventions.
A useful cross-check combines the provider ID, physical vehicle identity and destination asset code. Do not rely only on a fleet display name such as “Van 3.” That name may have been reused after a vehicle replacement. Historical readings and future service obligations should remain associated with the correct physical unit.
If an asset is retired, its site is inactive or its meter type is incompatible with the mapping, the connector requires review instead of silently changing the meter. Resolve the operational state first. Reopening a retired asset solely to make synchronization pass can attach new usage to equipment that should no longer receive current work.
When a vehicle is replaced or a telematics device is moved, revisit the mapping before the next automatic update. Provider identity, equipment identity and installed device identity can be related without being identical. The integration cannot infer your organization’s replacement policy from a familiar-looking vehicle name.
Verify units with a worked example
Samsara distance statistics arrive in metres, while the destination asset uses kilometres or miles. The connector converts metres to kilometres by dividing by one thousand, or to miles by dividing by 1609.344. Engine seconds are converted to hours by dividing by 3600. Imported meter values are rounded to two decimal places.
AI-generated editorial illustration; not a customer photograph or product screenshot.
For an illustrative distance sample of 125,000,000 metres, a kilometre asset receives 125,000 kilometres. The same source quantity corresponds to approximately 77,671.40 miles on a miles-based asset. For a runtime sample of 4,500,000 seconds, the destination value is 1,250 hours. These are arithmetic examples, not observed customer readings.
Check the conversion against a trusted source sample during the pilot. A plausible-looking value can still be wrong if the destination unit was configured incorrectly. A fleet that operates across regions should make unit choices explicit in its register rather than relying on each planner to remember which vehicles use miles.
Then compare the asset’s next maintenance threshold. A current reading of 125,000 kilometres and a next threshold of 126,000 kilometres express one thousand kilometres remaining. The threshold is an absolute reading, not the remaining distance. The integration updates the meter; it does not repair an incorrectly prepared maintenance plan.
Understand synchronization and skipped readings
Use Import latest readings to run an initial synchronization and review the imported and skipped counts. Enabled connections are polled every fifteen minutes for workspaces with active access. That polling interval is an application schedule, not a promise that the provider produces a fresh physical reading every fifteen minutes.
The connector reads the latest available vehicle-statistics snapshot and follows pagination. A source vehicle may have no value for the selected metric. A previously imported timestamp may appear again. A value may be lower than the current destination meter. Those cases can produce skipped readings rather than a new meter update.
Do not interpret a skipped count as a single universal error. It can mean that nothing new is available, that a mapping lacks the selected statistic or that a lower reading needs investigation. Compare the source statistic, timestamp, mapping and destination value to understand the specific situation.
Malformed values, invalid timestamps, unsupported bounds and incompatible asset states require correction. The connector validates the mapped data and uses a transaction when applying readings, so a rejected batch should not be treated as a successful partial synchronization. Review the connection result before relying on the new meter state.
Keep meter freshness separate from service completion
A successful reading import does not mean maintenance has been performed. It updates the usage evidence available to the existing meter-based maintenance process. The maintenance scheduler is responsible for generating due work according to the configured plans, and technicians still need to execute and close that work with the appropriate evidence.
Consider an illustrative vehicle at 49,800 kilometres with service due at 50,000. A later imported reading of 50,120 crosses that threshold. The operational response is to review the resulting due work and arrange service. Changing a threshold to 55,000 without a completed service record would hide the obligation rather than complete it.
Check the whole chain in the pilot: provider reading, destination meter, maintenance threshold, due work, assignment and closeout. A connector can move the right number while the organization still lacks a clear owner for the resulting job. That is a workflow gap rather than an API problem.
Maintain a process for vehicles that have not reported recently. A fifteen-minute polling job cannot create fresh usage when the source has none. Ask whether a manual reading or provider investigation is needed before making a maintenance decision from stale data.
Troubleshoot common discrepancies methodically
If no readings import, confirm that the connection is enabled, the workspace has active access, mappings exist and the selected provider statistic is available. Check the connection’s recorded failure information and run a deliberate manual synchronization after correcting the cause. Avoid changing several mappings and credentials at once, because that makes the original problem harder to identify.
AI-generated editorial illustration; not a customer photograph or product screenshot.
If a reading is lower than the asset meter, compare source selection and units first. Then investigate meter replacement, device movement or an earlier manual entry. The connector does not reduce the destination meter simply because the provider returns a smaller number. Resolve the discrepancy through a controlled asset-data review.
If the reading seems attached to the wrong vehicle, stop that mapping and verify the provider ID against the physical asset. Do not continue importing while hoping the next sample will clarify identity. Incorrect usage can influence future maintenance thresholds and create misleading service context.
If the provider returns an error or an unexpected response, the connection should remain a review item until a confirmed synchronization succeeds. Record the time, affected mapping and non-secret error context. Never include the API token in a diagnostic note or shared screenshot.
Plan credential changes and disconnection
When rotating a token, plan for the fact that existing mappings are cleared. Keep the reviewed vehicle-to-asset crosswalk so the connection can be rebuilt accurately. Verify the new credential’s account and permissions, recreate the intended mappings and compare the first reading with the prior baseline before returning to routine polling.
Removing an individual mapping stops updates to that asset through the mapping. Disconnecting removes locally stored credentials. If the token should no longer be usable at all, revoke it in Samsara as well. Local disconnection and provider-side revocation are separate actions with different effects.
When changing the integration owner, transfer the operational runbook and access responsibilities through your organization’s normal process. The runbook should identify the provider account, mapping source, unit conventions, error reviewer and maintenance owner without containing raw credentials.
Retain the explanation for intentional mapping changes. A future planner investigating a service interval should be able to understand why the source statistic changed, rather than seeing an unexplained jump in usage and assuming it represents normal vehicle operation.
Evaluate the pilot before expanding the fleet
Select vehicles that represent the actual variation in your fleet: distance and runtime use cases where relevant, different meter units if used, and at least one case where the selected statistic is unavailable. Verify successful behavior and understandable exceptions. A pilot that only tests the easiest vehicle leaves important operating questions unanswered.
AI-generated editorial illustration; not a customer photograph or product screenshot.
Set acceptance criteria before expanding. The source and destination identities should match, converted readings should reconcile, repeated samples should not create uncontrolled duplication and the maintenance team should know what to do when a reading is skipped. Then verify a real maintenance decision through the downstream plan and work-order process.
Measure reduced manual entry separately from equipment outcomes. Fewer copied meter readings may demonstrate administrative value. Reduced breakdowns or downtime require a longer and more careful evidence review. Use the maintenance evidence method before presenting causal claims about operational improvement.
Questions about the Samsara connection
Does this provide complete Samsara feature parity?
No. It imports selected vehicle odometer or runtime statistics into maintenance asset meters. Routing, driver safety, fuel-card activity and other specialist fleet workflows remain outside this connector. Evaluate those requirements separately when deciding how the two systems fit together.
Can we use our own account credentials?
Yes. A workspace manager supplies the appropriate read-only Samsara token through Integrations and explicitly maps vehicles to existing assets. The account still needs the relevant provider access and available statistics; entering a token does not create provider data that the account does not expose.
What is the first meaningful success check?
Confirm one vehicle’s identity, statistic, unit conversion and timestamp, then verify that the destination maintenance plan uses that meter correctly. A connected status alone is less informative than a reconciled reading and an understood next service obligation.