Samsara Integration Guide for FMC Partners

End-to-end implementation guidance for Fleet Management Companies integrating with Samsara across telematics, safety, maintenance, and workflows.

Executive Summary

Why Samsara

Samsara offers the breadth and depth of a true connected operations platform — bringing together telematics, safety, maintenance, and workforce solutions in a unified ecosystem trusted by the world’s largest fleets. With over two million connected devices and an open, extensible platform, Samsara provides the data accuracy, scalability, and reliability partners need to build differentiated, customer-ready solutions. Continuous product innovation and a rapidly growing partner ecosystem make Samsara the ideal platform for FMCs looking to deliver connected, data-driven value across every aspect of fleet management.

How FMCs Win With Samsara

Integrating with Samsara enables FMCs to expand their value proposition and unlock new revenue opportunities. Connected data from Samsara powers high-margin safety, telematics, and compliance offerings that drive measurable ROI for customers. FMCs can differentiate through modular, flexible technology packages that accelerate adoption, strengthen retention, and create recurring revenue through connected services. These integrations enhance — not compete with — the FMC platform, providing customers with operational insights that improve safety, optimize maintenance, and inform lifecycle planning.

This guide serves two purposes:

1. Document and help implement integrations that create a compelling joint value proposition. The Core + Operational Parity section reflects direct feedback from Samsara customers and FMC partners about the foundational data exchanges that drive their business processes. These are the capabilities customers assume “just work” when an FMC integrates with Samsara: vehicle visibility, engine data, maintenance reporting, and safety event sharing.
2. Inspire differentiation and deeper partnership. The Value-Add and Innovation section highlights emerging or advanced integrations that unlock greater efficiency and new business opportunities. Building these capabilities helps FMCs stand apart, positioning the partnership with Samsara as a strategic growth lever rather than simply a data connection.

Getting Started

Building a reliable, scalable integration with Samsara starts with a solid foundation. This section outlines the end-to-end steps required to design, test, and launch your integration, whether you’re authenticating via OAuth 2.0 or managing customer-provided tokens. Following these steps ensures your app is secure, properly scoped, and ready for Marketplace publication or private deployment. The process begins with becoming a Samsara developer, provisioning a sandbox for safe testing, and defining the right authentication model for your use case.

Implementation Checklist: Publishing and Auth Setup

Become a Samsara Developer and request a sandbox environment

• Join the Samsara Technology Partner Program to register as a developer. This will grant you access to a Samsara dashboard and developer portal to safely test APIs, authentication flows, and permissions. This sandbox contains simulated vehicles, drivers, and events to validate your integration end-to-end.

The developer sandbox is intentionally limited in both data depth and functionality. It is best used to validate authentication and API connectivity, not for production-grade data testing. For full validation — especially around telemetry, safety events, camera media, and workflow integrations — we recommend testing with a live customer account (with consent) or purchasing Not for Resale (NFR) hardware to create your own controlled test environment. This approach ensures realistic data, stable connectivity, and higher confidence before Marketplace submission.

Register your app (OAuth 2.0 only)

• Define redirect URIs for OAuth 2.0 callbacks.
• Choose Public App if you plan to publish on the Marketplace, or Private App for limited distribution.
• Manual-token integrations do not require app registration but should still track tokens per customer securely.

Define least-privilege scopes (both)

• Request only the endpoints your integration needs (e.g., /fleet/vehicles, /fleet/safety-events, /defects/stream).
• OAuth 2.0 / Marketplace Integration with Manual Token: Define scopes in your app registration for customer consent.
• Manual Tokens: Provide customers with a list of required scopes when they create tokens.
• Over-scoping complicates security reviews; under-scoping leads to missing data or failed integrations.

Implement authentication logic

• OAuth 2.0: Exchange authorization codes for access tokens and refresh tokens. Handle auto-rotation and refresh flows.
• Manual Tokens: Build secure token storage and retrieval logic; treat tokens as long-lived credentials.
• In both cases, associate tokens with a unique Samsara org ID for per-customer isolation and auditing.

Handle revocation gracefully

• Detect 401 or 403 errors and prompt re-authentication or new token generation.
• OAuth 2.0: Implement uninstall/revoke webhooks to automatically clean up tokens.
• Manual Tokens: Provide a customer-facing process for deleting or regenerating tokens when compromised.

Publish to the Marketplace (recommended)

• Create a clear Marketplace listing with description, logo, supported endpoints, and required scopes.
• Include a privacy statement, security summary, and contact information for support.
• Test your app thoroughly before submitting for review.
• Marketplace apps automatically handle per-org scoping and correct permissions.
• Certify the app to be published.

Manual token flows (if still used)

• Provide step-by-step instructions for customers to generate tokens and share them securely.
• Validate scopes programmatically on first API call and notify the customer if under-scoped.
• Track token ownership and expiration dates internally.
• Plan migration to OAuth 2.0 installs at the next renewal or upgrade cycle.

Authorization Choices

Choosing the right authentication model is one of the most important architectural decisions for your integration. The options below outline the trade-offs between OAuth 2.0 and manually managed tokens, as well as whether your app is published on the Samsara App Marketplace or distributed privately. Selecting the right approach impacts customer onboarding, security, scalability, and long-term maintainability of your integration.

	OAuth 2.0 (Listed in Marketplace)	Manual Tokens (Customer-Provided, Listed in Marketplace)	OAuth 2.0 (Private / Unlisted App)	Manual Tokens (Customer-Provided, Unlisted / Ad Hoc)
Install and onboarding	Self-serve from the Samsara App Marketplace with a consent screen and clear branding. Clean, repeatable installation experience that requires no manual token exchange.	Customer manually creates API tokens using a published integration’s documentation and sends them to the partner for configuration. Visible listing, but setup remains manual.	Direct OAuth link or hosted consent flow outside the Marketplace; works for pilots or limited rollouts but lacks discovery and trust signaling.	Customers manually generate and share tokens through email or ticketing. No listing, no standardized process, high friction.
Visibility and trust	Public Marketplace listing clearly states data use, security practices, and scopes. Demonstrates reliability and earns customer confidence.	Customers can reference a trusted listing, but manual token exchange weakens perceived security and increases onboarding friction.	Trusted only via your own documentation or reputation. No public listing.	Completely opaque; each engagement requires a fresh security and procurement review.
Org scoping and traceability	Automatic. Each token is uniquely scoped to the installing org and easily audited. Tokens cannot cross org boundaries.	Tokens are manually generated per org but prone to errors in scoping and management. Difficult to trace back to a specific install.	Scoped per org through your own OAuth logic, but you must enforce tenant mapping and log auditing.	Weakest. Tokens often reused across customers or environments with no clear ownership trail.
Scopes (least privilege)	Enforced at install. Customer reviews and approves exact scopes needed for your app; prevents both over- and under-scoping.	Customer-generated token based on your app’s configured scopes.	You define scopes programmatically, but the customer sees only your hosted consent UI; risk of miscommunication.	Scopes are arbitrary and inconsistent; little control over correctness.
Under-scoping impact	Prevented. Marketplace ensures all required scopes are authorized before install completes.	Prevented. Marketplace ensures all required scopes are authorized before install completes.	Possible if your app fails to request all required scopes; debugging falls to partner.	Very common; integrations routinely fail to retrieve complete datasets.
Token lifecycle	Short-lived access tokens and refresh tokens; rotation and expiry handled automatically through OAuth.	Long-lived API tokens; must be manually rotated and replaced by the customer when expired or compromised.	Same as Marketplace for token types, but you must host your own refresh/re-auth flow.	Long-lived static secrets that rarely rotate; high operational and security risk.
Revocation and isolation	Customers can revoke or uninstall directly in the Samsara UI; tokens invalidated instantly without partner action.	Customer can manually delete tokens, but partners are rarely notified; difficult to detect.	Revocation works per consent, but your app must handle invalid-token errors gracefully.	No automatic revocation; relies entirely on customer communication.
Per-tenant isolation	Guaranteed; each org authorizes separately; no shared credentials.	Partial; tokens are customer-specific but easily mismanaged or stored together.	Strong if implemented correctly; you must enforce isolation.	Weak; shared handling of secrets across tenants is common.
Error handling and telemetry	Standardized; consistent scope and token behavior simplify error handling and monitoring.	Standardized; consistent scope and token behavior simplify error handling and monitoring.	Moderate consistency; depends on your app’s validation logic.	Unpredictable; troubleshooting dominated by credential issues.
Support burden	Lowest. Automated install, clear scopes, automatic token rotation.	High; manual corrections for expired or revoked tokens are common.	Moderate; requires manual re-auth coordination and some customer assistance.	Highest. Frequent credential mix-ups and expired tokens drive support noise.
Compliance and security posture	Best; auditable per-org authorization, no long-lived secrets, scoped access.	Acceptable but risky; manual token sharing introduces exposure risk.	Strong if implemented securely but lacks centralized oversight.	Poor; long-lived secrets, no auditability, frequent reuse.
Discoverability	Publicly searchable on the Samsara App Marketplace; accessible via category and API listings.	Listed app provides some awareness but manual setup limits adoption.	Hidden/private; discoverable only through your outreach.	None; completely private and invisible to customers.
Best for	Production-grade, multi-tenant partner apps that require discoverability, scalability, and minimal manual work.	Transitional or small-scale deployments where Marketplace listing exists but automation is incomplete.	Controlled pilots, internal partner testing, or phased launches before Marketplace listing.	Ad-hoc scripts, one-off integrations, internal tooling, or POCs only.

Summary Table of Integration Endpoints

What Customers Expect: Core and Operational Parity

Category	Integration Item	Data Flow	API Function	Endpoint Path(s)
Admin	Vehicle Sync (List + Update)	Bidirectional	GET / PATCH	/fleet/vehicles, /fleet/vehicles/{id}
Telematics	Vehicle GPS Location	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Telematics	Odometer Miles	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Telematics	Engine Hours	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Telematics	Engine ON/OFF Events	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Maintenance	Fuel Level	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Maintenance	Engine Diagnostics (Fault Codes)	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Maintenance	Ambient Air Temperature	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Maintenance	Engine Oil Pressure	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Maintenance	Battery Voltage	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Maintenance	eDVIR (Driver Vehicle Inspection Reports)	Bidirectional	GET / PATCH	/defects/stream, /fleet/defects/{id}
Maintenance	EV Battery Stats	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Maintenance	Tire Pressure	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Maintenance	Oil Life	Samsara → FMC	GET	/fleet/vehicles/stats/feed
Safety	Safety Events (Vehicle Gateway Generated)	Samsara → FMC	GET	/fleet/safety-events
Safety	Speeding Events	Samsara → FMC	GET	/fleet/vehicles/driver_speeding_intervals
Assignments	Driver User Sync (Create/Update)	Bidirectional	GET / POST / PATCH	/fleet/drivers, /fleet/drivers/{id}

Differentiation: Value-Add and Innovation

Category	Integration Item	Data Flow	API Function	Endpoint Path(s)
Admin	Sync Branches / Groups / BUs (Tags)	Bidirectional	GET / POST / PATCH	/tags, /tags/{id}
Assignments	Driver–Vehicle Assignments	Bidirectional	GET / POST / PATCH / DELETE	/fleet/driver-vehicle-assignments
Telematics	Vehicle Trips	Samsara → FMC	GET	/fleet/trips
Telematics	Idling Events	Samsara → FMC	GET	/fleet/vehicles/idling-intervals
Compliance	IFTA Reporting	Samsara → FMC	GET	/fleet/vehicles/stats/feed, /fleet/trips, /fleet/vehicles
Workflows	Forms and Issues	FMC ↔ Samsara	GET / POST	/forms, /issues
Safety	Camera Media	Samsara → FMC	GET	/fleet/safety-events/media
Driver Comms	Messages	Bidirectional	GET / POST	/messages

Core and Operational Parity

These integrations form the foundation of every successful FMC ↔ Samsara partnership. They are based on direct feedback from fleet operators and FMC customers who consistently identified these data flows as essential to daily operations. Each subsection describes the purpose and endpoints involved, implementation details explaining data flow and important fields to capture, and value to FMC users — how the integration improves customer workflows.

Admin

Vehicle Sync (List + Update)

• Endpoint(s): /fleet/vehicles, /fleet/vehicles/{id} — API Reference
• Implementation Details: The FMC should query /fleet/vehicles to obtain the authoritative list of all vehicles in a customer’s organization. Each vehicle record includes vehicleId, name, licensePlate, vin, and externalIds. When the FMC needs to update metadata (e.g., assign external tags, adjust naming, or add custom fields), it can send PATCH requests to /fleet/vehicles/{id}. Data flows primarily from Samsara to FMC for synchronization, with optional updates flowing from FMC to Samsara for metadata enrichment. Key data points to capture:
  • vehicleId → persistent unique identifier
  • vin → vehicle ownership and maintenance link
  • licensePlate → regulatory reporting and driver assignment reference
  • externalIds → cross-system linking for FMC internal IDs
• Value to FMC Users: Keeps both systems aligned on vehicle inventory and metadata. Fleet managers gain a consistent view of assets across maintenance, billing, and analytics workflows, reducing double entry and mismatched records.

Telematics

Vehicle GPS Location

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: Samsara’s stats feed delivers real-time GPS data including latitude, longitude, heading, speed, and reverseGeocode. The FMC should capture these points with timestamps and vehicleId to drive location services and trip tracking. Combine coordinates with VIN and gateway metadata for auditability. The data flows from Samsara → FMC in near real time.
• Value to FMC Users: Powers live fleet maps, dispatch visibility, and ETA prediction. Customers gain a single pane of glass for vehicle tracking without needing separate telemetry feeds.

Odometer Miles

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: Retrieves gpsOdometerMeters and obdOdometerMeters. Use OBD-based values when available for accuracy; fall back to GPS when not. Convert meters to miles or kilometers and store historical snapshots for each vehicle. Data flows from Samsara → FMC.
• Value to FMC Users: Supports accurate lease billing, preventive maintenance, and regulatory mileage tracking.

Engine Hours

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: Exposes obdEngineSeconds as the cumulative engine runtime. Convert to hours and track daily increments. Include with VIN and vehicle status data for maintenance planning.
• Value to FMC Users: Provides a reliable measure of vehicle utilization, especially for off-road assets where distance is not a good proxy for wear.

Engine ON/OFF Events

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: Uses engineStates to indicate On, Off, or Idle status. The FMC should log state transitions with timestamps and link to driver assignments to analyze behavior and idle time.
• Value to FMC Users: Provides insight into fuel waste and utilization patterns, empowering operators to reduce idle time and improve efficiency.

Maintenance

Fuel Level

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: The fuelPercents field reports tank level as a percentage. FMCs should capture this with vehicleId, VIN, and timestamp. Combine with trip data for fuel economy analysis and with external fuel purchase feeds for validation.
• Value to FMC Users: Enables fuel cost optimization and exception reporting for potential theft or inefficiency.

Engine Diagnostics (Fault Codes)

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: Returns active and historical DTC codes via faultCodes. Store these with vehicleId, timestamp, and engineStates to correlate faults with conditions. Provide mechanics and maintenance teams with API access to real-time diagnostics.
• Value to FMC Users: Improves preventive maintenance programs and reduces downtime by detecting issues early.

Ambient Air Temperature

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: The ambientAirTemperatureMilliC field provides environmental temperature readings. Capture alongside engine metrics for contextual analysis of performance in extreme weather.
• Value to FMC Users: Supports diagnosis of temperature-related faults and planning for seasonal maintenance.

Engine Oil Pressure

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: Uses engineOilPressureKPa to monitor engine health. Convert to PSI and establish alerts for low pressure thresholds. Correlate with engine speed and load for trend analysis.
• Value to FMC Users: Prevents catastrophic engine failures through early detection of oil-pressure anomalies.

Battery Voltage

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: Retrieves batteryMilliVolts. FMCs should set thresholds for low voltage conditions and notify service teams. Capture with timestamp and vehicleId for trend analysis.
• Value to FMC Users: Reduces roadside failures and maintenance costs by enabling proactive battery replacement.

eDVIR (Electronic Driver Vehicle Inspection Reports)

Endpoints:

• GET /defects/stream — API Reference
• GET /defect-types — API Reference
• PATCH /fleet/defects/{id}

Implementation Details:

Samsara’s eDVIR system enables digital pre- and post-trip vehicle inspections completed by drivers through the Samsara Driver App. These inspections identify and document defects or issues associated with specific vehicles and assets.

Data Flow: Data primarily flows from Samsara → FMC, as Samsara collects driver inspection results and defect data. FMCs can also push resolution updates back to Samsara, closing the loop by marking defects as repaired once maintenance actions are completed.

Key API Usage:

1. Retrieve active and historical defects

   Use GET /defects/stream to pull a continuous feed of driver-submitted defect records. Each record includes:

   • defectId — unique defect identifier
   • vehicleId and optional assetId — identifies the equipment inspected
   • driverId — links the inspection to the operator
   • startTime / endTime — timestamp range of the inspection
   • isResolved — boolean flag indicating current status
   • notes or description — driver-entered details
   • defectTypeId — numeric code identifying the type of defect
2. Map defect categories for context

   Use GET /defect-types to retrieve Samsara’s standardized list of defect categories and their human-readable labels (e.g., Brakes, Lights, Body Damage). FMC systems should cache this list to:

   • Classify defect reports by category
   • Provide consistent terminology in customer-facing interfaces
   • Support analytics across large fleets (e.g., “Top 5 recurring defect categories”)
3. Update and resolve defects

   Once an FMC maintenance workflow resolves a reported defect, use PATCH /fleet/defects/{id} to update its status:

   {
     "isResolved": true,
     "resolutionNotes": "Brake pads replaced at depot A on 2025-10-05"
   }
   

   This two-way update ensures the Samsara dashboard reflects current maintenance actions and closes the DVIR compliance loop.

Data to Capture:

• defectId and defectTypeId for relational tracking
• vehicleId, driverId, and timestamps for operational context
• notes, resolutionNotes, and isResolved for reporting and compliance
• Any attachments or photos associated with the inspection (available via media links in Samsara UI)

Value to FMC Users: This integration allows FMCs to ingest all driver inspection data, automatically create maintenance work orders, and synchronize repair status back to Samsara. Drivers benefit from faster feedback on reported issues. Maintenance teams have a single, accurate source of inspection data. Customers meet DOT and internal safety compliance requirements without manual paperwork. By combining the Defects Stream and Defect Types APIs, FMCs can deliver full-lifecycle visibility, from issue reporting to repair verification, directly within their fleet maintenance portals.

EV Battery Stats

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: Exposes EV-specific metrics such as evStateOfChargePct, evBatteryRangeMeters, and chargingStatus. The FMC should log these values and aggregate daily averages to support EV readiness dashboards.
• Value to FMC Users: Helps customers manage charging schedules and monitor battery health to maximize EV uptime.

Tire Pressure

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: Returns pressure readings per tire when supported by OBD. Capture pressure and temperature values and flag out-of-range conditions.
• Value to FMC Users: Reduces tire wear and fuel consumption through early detection of under- or over-inflation.

Oil Life

• Endpoint(s): /fleet/vehicles/stats/feed — API Reference
• Implementation Details: Field oilLifeRemainingPct (where available) indicates time to next oil service. The FMC can aggregate these values to trigger maintenance work orders.
• Value to FMC Users: Automates preventive maintenance planning and reduces engine wear through timely service alerts.

Safety

Safety Events

• Endpoint(s): /fleet/safety-events — API Reference
• Implementation Details: The Safety Events API provides a unified feed of vehicle and driver behavior data, combining telematics-based harsh events and, when available, AI dashcam detections. Each event record includes details such as vehicleId, driverId, timestamp, location, behaviorLabel, and optional mediaUrls if camera footage is available. Without a Samsara AI Dashcam installed, events are limited to gateway-based detections like harsh braking, acceleration, and turning. When a dashcam is present, additional AI detections such as tailgating, phone use, or following distance violations are added to the same event feed. The FMC should ingest this data, store event types with driver and vehicle context, and surface it in dashboards or risk reports.
• Value to FMC Users: Enables a single, consistent view of driver safety performance. Customers can use this data to run driver coaching programs, benchmark safety scores, and share analytics with insurers for potential premium benefits.

Speeding Events

• Endpoint(s): /fleet/vehicles/driver_speeding_intervals — API Reference

• Implementation Details: The Speeding Intervals API provides granular speeding event data for each driver and vehicle, including start and end times, duration, location, and the magnitude of the speed violation. Each record includes:

  • driverId and vehicleId for attribution
  • startTime and endTime for interval boundaries
  • distanceMeters and durationSeconds for contextual severity
  • averageSpeedMph and speedLimitMph to quantify the violation

  FMCs should collect and store this data for safety scoring, risk analytics, and reporting dashboards. The data flows from Samsara → FMC, with daily or on-demand retrieval to monitor compliance and risky behaviors.

• Value to FMC Users: Offers precise, time-bounded speeding analytics that enhance safety program insights. Customers can track recurring violations, benchmark fleet performance, and target coaching to high-risk drivers.

Assignments

Driver User Sync (Create/Update)

• Endpoint(s): /fleet/drivers, /fleet/drivers/{id} — API Reference
• Implementation Details: FMCs can pull driver profiles from Samsara and create or update records as needed. Important fields include driverId, name, email, externalIds, and licenseNumber. When creating drivers via POST, provide external IDs to ensure traceability back to the FMC system. Bidirectional updates keep driver rosters in sync.
• Value to FMC Users: Eliminates duplicate data entry and keeps operator information accurate for compliance, reporting, and assignment management.

Key Consideration: Driver and Vehicle Sync

For FMCs and Samsara customers, ensuring that vehicles and drivers remain synchronized across both platforms is critical to delivering a unified customer experience. Accurate records underpin every downstream workflow, from maintenance scheduling and compliance to reporting, billing, and analytics. Because data can originate in either system, it’s important to define and enforce a clear synchronization strategy for vehicles and drivers.

In some cases, the FMC acts as the system of record. For example, when new vehicles are onboarded through financing or leasing workflows, these records should be pushed to Samsara via the Vehicle API to automatically provision telematics devices and maintain alignment. In other cases, Samsara may create or update records first, such as when a customer installs a new gateway or adds a driver directly through the Samsara dashboard. Those updates should flow back to the FMC platform to ensure consistency in asset lists and driver rosters.

There will also be scenarios where both systems add items independently. For example, when the FMC imports vehicles from a third-party source while Samsara automatically detects new hardware. In these situations, the integration must perform matching based on persistent identifiers such as VIN, license plate, or unique external IDs. Matching logic should include both deterministic keys (exact VIN or serial number match) and fuzzy logic (partial name or field matches) to handle differences in formatting or data entry. Once records are linked, the integration should maintain a shared reference ID between systems to prevent future duplication.

To keep data synchronized over time, FMCs should:

• Define clear ownership rules for each data domain (e.g., vehicles owned by FMC, drivers by Samsara, assignments bidirectional).
• Use periodic reconciliation jobs or API audits to detect and resolve mismatched or missing records.
• Employ webhook or polling-based update triggers to ensure near real-time sync without data lag.

With these best practices, FMC and Samsara systems stay in sync automatically, ensuring that both remain authoritative sources of truth for shared customers. This alignment eliminates manual reconciliation, reduces support overhead, and enables seamless cross-system workflows for maintenance, assignments, and compliance reporting.

Differentiation Use Cases: Value-Add and Innovation

Beyond core operational parity, this section highlights integrations that extend the Samsara–FMC partnership into advanced analytics, compliance automation, and AI-powered insights. It includes capabilities such as driver behavior analytics (e.g., speeding and idling), organizational data management, and workflow automation — enabling FMCs to deliver richer customer experiences and data-driven value.

Admin

Sync Branches / Groups / BUs (Tags)

• Endpoint(s): /tags, /tags/{id}

• Implementation Details: FMCs can manage organizational structures within Samsara using the Tags API.

  • GET /tags retrieves all existing tags and their hierarchical relationships (tagId, parentTagId).
  • POST /tags creates new groups or branches.
  • PATCH /tags/{id} updates names or associations.

  Each vehicle, driver, or asset can be linked to multiple tags. Data flows bidirectionally: Samsara exposes tag hierarchies, while the FMC can create or modify them to align with its customer’s business units or cost centers.

• Value to FMC Users: Enables fine-grained reporting and billing by department or region. FMC users can mirror corporate structures directly in Samsara, supporting role-based views and cost allocation.

Assignments

Driver–Vehicle Assignments

• Endpoint(s): /fleet/driver-vehicle-assignments

• Implementation Details: FMCs can both fetch and modify driver-to-vehicle pairings.

  • GET retrieves current assignments (driverId, vehicleId, startTime, endTime).
  • POST and PATCH establish or update pairings when the FMC acts as the source of truth.
  • DELETE removes outdated assignments.

  Capturing these relationships ensures accurate mileage, fuel, and safety event attribution.

• Value to FMC Users: Maintains consistency between dispatch systems and Samsara data, ensuring accurate driver analytics and compliance reporting.

Workflows

Forms and Issues

• Endpoint(s): /forms, /issues — API Reference

• Implementation Details: The FMC can leverage Samsara Forms and Issues APIs to create or respond to workflow events.

  • Use /forms to present checklists or surveys to drivers in the Samsara Driver App.
  • Use /issues to log, update, and resolve operational problems (e.g., vehicle damage, missing equipment).

  Data can flow in both directions: FMC systems can generate an issue based on customer input, or Samsara can post new driver-submitted data to the FMC’s maintenance or CRM systems.

• Value to FMC Users: Creates connected workflows between back-office systems and on-road users, eliminating paper processes and accelerating issue resolution.

Safety

Camera Media

• Endpoint(s): Media API (/fleet/safety-events/media)
• Implementation Details: FMCs can use the Media API to retrieve dashcam images and video clips linked to safety events. Responses include time-bound S3 URLs, vehicleId, driverId, and behaviorLabel. Because videos may contain personally identifiable information, secure access policies and retention settings must be observed. Data flows one way — from Samsara to FMC — where media files are ingested and associated with event records for review or coaching.
• Value to FMC Users: Provides visual verification of incidents, supporting claims management, exoneration, and driver safety training programs.

Telematics

Vehicle Trips

• Endpoint(s): /fleet/trips
• Implementation Details: Retrieves detailed trip segments including startLocation, endLocation, distanceMeters, durationSeconds, and optional route geometry. The FMC can enrich this data by linking trips to driver assignments and business units. Data flows from Samsara → FMC, enabling trip reconstruction, benchmarking, and anomaly detection.
• Value to FMC Users: Enables route optimization, utilization reporting, and cost analysis based on actual driving patterns rather than static telemetry.

Idling Events

• Endpoint(s): /fleet/vehicles/idling-intervals

• Implementation Details: The Idling Events API provides detailed intervals of time during which a vehicle’s engine is running but the vehicle is not in motion. This data helps identify wasted fuel, unnecessary engine wear, and potential environmental inefficiencies. Each returned record includes:

  • vehicleId — identifies the specific vehicle
  • driverId (if available) — attributes idle time to a driver
  • startTime / endTime — timestamps defining the idling interval
  • durationSeconds — total time spent idling
  • location — latitude and longitude of where the idle occurred
  • fuelConsumedMl — estimated fuel consumed during the idle period

  The FMC should ingest this data on a regular cadence and aggregate results to build idling KPIs across fleets, vehicles, and drivers. This API is complementary to the stats/feed endpoint but offers higher-level summaries of idle intervals, which are better suited for performance dashboards and sustainability reporting.

  Data Flow: Data flows from Samsara → FMC, providing interval-level metrics that can be merged with trip and driver data. FMC systems should store historical idling intervals to track trends and compute idle-time ratios (e.g., total idle time per operating hour).

• Value to FMC Users: Reduces operating costs and supports sustainability goals by exposing where and when vehicles are idling unnecessarily. Fleet managers can use this data to:

  • Identify vehicles with excessive idle time
  • Implement idling reduction policies and driver training
  • Quantify fuel savings and emission reductions over time

  By integrating idling interval data, FMCs deliver meaningful operational insights and position themselves as strategic partners helping customers meet both cost and ESG objectives.

Beyond These Integrations

The Samsara platform offers a wide range of additional capabilities that FMCs can leverage to create deeper, more intelligent solutions for their customers. While this guide focuses on the most common and well-defined integration patterns, several other areas of opportunity exist where FMCs can collaborate closely with Samsara to expand the partnership:

• Connected Maintenance: FMCs can use Samsara’s advanced AI-driven maintenance capabilities as a powerful gateway to grow their maintenance programs and capture additional repair revenue. Samsara’s platform continuously analyzes diagnostic fault codes, sensor readings, and historical patterns across millions of connected vehicles to detect emerging issues before they become critical failures. This predictive intelligence enables FMCs to reach customers at the exact moment service is needed, driving vehicles back into their preferred maintenance networks. By integrating these insights directly into their maintenance management workflows, FMCs can automate service scheduling, parts ordering, and customer notifications, reducing downtime and improving the overall service experience. For the FMC, this is not only an operational advantage — it’s a commercial one. Predictive and condition-based maintenance programs powered by Samsara’s AI expand the addressable fleet footprint under management, increase service bay utilization, and generate high-margin recurring revenue through data-informed repair programs.
• Routing: Explore AI-powered routing and dispatch capabilities that dynamically optimize routes using AI optimizations, vehicle condition, and job requirements data.
• Insurance Partner Programs: Collaborate on insurance data-sharing programs that leverage Samsara’s safety analytics to reduce premiums and incentivize safe driving behavior.
• Asset Tracking: Extend integrations beyond vehicles to include unpowered assets such as trailers, equipment, and tools, delivering full-fleet visibility across the customer’s operations.
• Connected Workforce: Tap into Samsara’s worker safety and compliance capabilities to support incident reporting, fatigue monitoring, and location-aware job safety workflows.
• Implementation and Installation Services: Partner with Samsara’s professional services and certified installer network to simplify onboarding and ensure accurate device installation at scale.
• Strategic Advisory Services: FMCs can leverage Samsara’s connected data and insights to expand beyond technology delivery and into a premium, consultative offering that drives new revenue streams and deeper customer engagement. By combining operational data from Samsara with the FMC’s domain expertise in maintenance, compliance, and lifecycle management, these services help customers turn information into action. Through performance benchmarking, fleet optimization workshops, and data-driven business reviews, FMCs can guide customers toward measurable improvements in safety, fuel efficiency, maintenance costs, and asset utilization.

FMC partners interested in exploring these additional opportunities should contact their Samsara Partner Account Manager for more information.

Migration Strategies

Moving from Manual Tokens to OAuth 2.0 Installs

As your integration matures and your customer base grows, transitioning from manual token management to OAuth 2.0-based authentication is one of the most impactful upgrades you can make. It improves security, reduces support overhead, and provides customers with a more seamless installation experience. This process can be done incrementally with minimal disruption if planned correctly.

1. Inventory your existing manual-token customers

   Create a list of customers currently using manually shared API tokens. This enables you to track the associated org IDs, expiration dates, and scopes for each token, and identify which tokens are already over- or under-scoped and where permissions are missing (e.g., DVIR, trips, or safety events).

2. Develop and publish your new OAuth 2.0 app

   Register your app in the Samsara Developer Portal. Request the appropriate least-privilege scopes. Then test end-to-end using your sandbox environment to confirm parity with your current manual-token integration. Once validated, publish the app to the Samsara App Marketplace for self-serve installs.

3. Communicate the benefits to customers

   Provide customers with a clear explanation of why this migration improves their security and experience:

   • OAuth 2.0 tokens are org-scoped, ensuring that credentials can’t be misused across tenants.
   • Tokens rotate automatically, reducing manual effort and eliminating downtime from expired credentials.
   • Customers can revoke access directly in their Samsara dashboard for full control.

   Make sure customers understand that this transition is a best-practice upgrade and not just a technical change.

4. Provide a Reconnect or Upgrade flow

   Add a Reconnect button or endpoint within your app’s UI or backend that triggers the OAuth 2.0 authorization flow. When the customer installs the Marketplace app, record their org ID and new OAuth 2.0 tokens, then safely deactivate their manual token. Provide in-app or email confirmation once the migration is complete.

5. Run parallel operation (optional)

   For a short transition period, support both auth methods. This allows the team time to validate that OAuth 2.0 tokens produce identical or more complete datasets compared to manual tokens. Once confirmed, set an internal cutoff date for manual-token deprecation.

6. Set a sunset policy for manual tokens

   Communicate a clear deprecation timeline (e.g., “Manual tokens will no longer be supported after [date]”). Make sure to provide advance notifications and reminders to customers who haven’t migrated. Then disable or delete old tokens once the OAuth 2.0 installation is confirmed to prevent accidental reuse.

7. Update documentation and support materials

   Update integration docs, implementation guides, and FAQ content to make OAuth 2.0 the default method. Clearly label the manual-token flow as “legacy” and ensure your support team has scripts and checklists to help customers migrate smoothly.

Avoiding v1/Deprecated APIs and Migrating to Current Endpoints

Using current, supported APIs is essential for reliability, security, and long-term compatibility. Deprecated (often “v1”) endpoints may lack features, return incomplete data, or be removed with limited notice. This section explains how to identify deprecated endpoints in your integration, plan a safe migration, and prevent future drift.

Why this matters

Current endpoints typically have clearer scopes, stronger auth models (OAuth 2.0), better pagination and filtering, richer metadata, and more consistent error semantics. Migrating off deprecated routes reduces support noise, prevents silent data gaps, and keeps your app aligned with Samsara’s roadmap.

How to recognize a deprecated endpoint

• Naming or docs indicate “v1,” “legacy,” or “deprecated.”
• The reference notes a replacement route (for example, a consolidated or resource-scoped path).
• Missing modern features (e.g., refined filters, proper pagination tokens, consistent field naming, or OAuth 2.0 scopes).
• Inconsistent or non-resourceful URL patterns compared to newer endpoints.

Common differences to expect and how to handle them

• Authentication and scopes: Move from long-lived manual tokens to OAuth 2.0; validate scopes programmatically and surface clear re-auth prompts on 401/403.
• Resource shapes: Field renames, nested objects, and enum changes are typical. Maintain a mapping table and unit tests for your serializer/deserializer.
• Pagination: Token-based pagination replaces offset/limit. Store and pass nextPageToken (or equivalent) until exhaustion.
• Time and units: Prefer ISO 8601 with timezone awareness; standardize units (meters vs. miles, seconds vs. milliseconds) at your boundary layer.
• Filtering and queries: Newer endpoints often require explicit time windows or IDs. Tighten queries to reduce payload size and improve throughput.
• Webhooks and polling: Where available, use event/webhook triggers to reduce polling. Keep idempotent handlers and retry with backoff.

Quick tips to avoid future drift

• Treat endpoint changes as a productized process: single owner, checklist, and release notes every time.
• Add contract tests that validate shape, enums, and required fields against live sandbox responses.
• Log the endpoint version and org ID on every call to make tenant-specific issues easy to diagnose.
• Periodically review the developer reference to catch early deprecation notices and new capabilities that can replace custom logic.

Mapping Deprecated Endpoints to Production Ready Endpoints

Area	Legacy v1 Endpoint (example)	Modern Replacement	Notes
Vehicles – list	GET /v1/fleet/vehicles	GET /fleet/vehicles	Core vehicle inventory.
Vehicles – single	GET /v1/fleet/vehicles/{id}	GET /fleet/vehicles/{id}	Retrieve a single vehicle by ID.
Drivers – list/create/update	GET/POST/PATCH /v1/fleet/drivers	GET/POST/PATCH /fleet/drivers, GET /fleet/drivers/{id}	Use externalIds for cross-system linking.
Driver–Vehicle Assignments	GET/POST/PATCH/DELETE /v1/fleet/vehicles/driver-assignments	GET/POST/PATCH/DELETE /fleet/driver-vehicle-assignments	Consolidated model and filters.
Safety Events	GET /v1/fleet/safety-events	GET /fleet/safety-events	Unified harsh + AI events feed.
DVIR – defects stream	GET /v1/fleet/defects/stream	GET /defects/stream	Streaming driver-submitted defects.
DVIR – defect types	GET /v1/fleet/defect-types	GET /defect-types	Use to label and group defects.
DVIR – resolve defect	PATCH /v1/fleet/defects/{id}	PATCH /fleet/defects/{id}	Close the loop after maintenance.
Locations – latest	(various v1 location reads)	GET /fleet/vehicles/locations	Snapshot locations.
Locations – history	(various v1 location reads)	GET /fleet/vehicles/locations/history	Historical breadcrumb tracks.
Locations – feed	(various v1 location reads)	GET /fleet/vehicles/locations/feed	Follow-style stream.
HOS – daily logs	GET /v1/fleet/drivers/{driverId}/hos_daily_logs	GET /fleet/hos/daily-logs	Modern daily summaries.
HOS – logs	GET /v1/fleet/hos_logs	GET /fleet/hos/logs	Detailed duty status logs.
HOS – ELD events	GET /v1/fleet/hos_eld_events	GET /fleet/hos/eld-events	Raw ELD event records.
Addresses	GET/POST/PATCH/DELETE /v1/addresses	GET/POST/PATCH/DELETE /addresses	Consistent CRUD pattern.
Tags	GET/POST/PATCH/DELETE /v1/tags	GET/POST/PATCH/DELETE /tags	For groups/BUs/hierarchy.
Users (admins)	GET/POST/PATCH/DELETE /v1/users	GET/POST/PATCH/DELETE /users	Admin user management.