Routing

This guide provides an overview of best practices when building a route planning integration with Samsara.

For an overview of how routing works in the Samsara Dashboard and Driver app, see these knowledge base articles:

• Routes Overview
• Creating Routes in the Dashboard
• Routing in the Driver App

Key concepts

Route A planned sequence of 2 or more stops assigned to a specific driver or vehicle within a timeframe. Samsara refers to loads as routes.

Stop (sometimes called a Route Stop) is a single location within a Route where a driver is scheduled (or required) to perform a specific action.

Route tracking

Samsara uses the Samsara Vehicle Gateway to automatically track route progress.

Samsara tracks routes sequentially and selects the route with the earliest scheduled start time to track first.

The Route Stop Arrival & Configuration article provides an in-depth guide on different route stop states and how ETAs are calculated.

Route assignment

A Route be unassigned or assigned either a Driver or a Vehicle. We recommend assigning routes to the entity that is least likely to change during the progress of a route.

• Vehicle - Assign routes to vehicles if the driver might change throughout the progress of the route.
• Driver - Assign routes to drivers if the vehicle or trailer are unknown ahead of time or might change.

Unassigned routes can either be assigned later by editing the route, or they can be claimed by drivers through the Driver App if that setting is turned on. See Creating Routes for details and example code.

Route stops

A route stop represents the customer location for whom you are servicing one or more orders. Route stops have a number of qualities:

• Route Stop Destination (Geofence)
• Scheduled/actual arrival time of the stop
• Scheduled/actual departure time of the stop
• Stop state information and timestamps (en route, arrived, departed, etc. see Route Stop Arrival & Configuration)
• Notes (to list orders, driver instructions, etc)

Orders (represented as notes)

Samsara doesn’t have a first-class "order" entity. Samsara treats routes and stops as the primary scheduling blocks. Instead, all order-related details (e.g., SKUs, purchase order numbers, gate codes, customer contact info) are passed using the notes field on each stop. Decide how you want to store order information depending on your use case:

• Truckload (entire route represents a single order): Use the route's name and notes fields to store order information.
• 1 Order per stop (single order at a single location): Use the stop's name and notes fields to store order information.
• Multiple orders per stop (multiple orders at a single location):
  • Option 1 - combined orders: Use the stop's notes field to list each order at that location.
    • Pros: Does not require manual stop arrival or depart for drivers.
    • Cons: Arrival and departure to and from the location's geofence trigger only once so all orders will have the same En Route, ETA, Arrival, and Departure times.
  • Option 2 - individual orders: Create multiple stops using the same location, each representing an order. Require drivers to manually arrive or depart each stop to signal delivery of each order.
    • Pros: Each order's state is unique to that order, depending on when the driver manually arrives or departs from that order's stop.
    • Cons: Requires that the driver manually arrive or depart from each stop since they all have the same location geofence.

Order delivery windows

A delivery window (i.e. service window, appointment window) is a time window within which the driver must complete the order. Examples of this include a negotiated appointment slot and the open/close times for a store.

Samsara doesn’t have an explicit delivery window concept. Instead, we recommend storing delivery window information on the route stop's notes and using the route stop's scheduledArrivalTime and scheduledDepartureTime to indicate the delivery window.

Instructions

Often times a driver may have specific instructions or information they need to be aware of, whether it is the gate code or the phone number for the individual receiving the delivery.

Route stop instructions are added as free form route stop notes.

See Creating Routes for details and sample code.

Tasks

When a driver arrives at a stop, they might have a series of tasks to complete (e.g. unload goods, complete Bill of Lading, complete Proof of Delivery, check reefer temperature).

In the Samsara Driver App, tasks are represented by Samsara Documents. Samsara Documents are custom forms that can be set up in the Samsara Dashboard for drivers to fill out during their day as needed. For more on documents, see the Documents knowledge base article.

Documents can be attached to a Route Stop as a Task for the driver to do.

See Creating Stop Tasks for details and sample code.

Configuration

Samsara customers operate in a wide set of fleet configurations. In order to support many different types of businesses, settings are exposed to control the behavior of the routing product.

Dispatch settings

Navigate to Settings > Dispatch

Notice there are settings for tracking windows, arrival and departure settings, amount of time at a stop, and route stop timeliness.

Please see the route overview knowledge base article for more information about how to configure your organization’s dispatch settings.

Driver app settings

Navigate to Settings > Driver App

Here you’ll find settings to configure how drivers experience the Driver app. Under the features tab, the routes section has controls for how the app handles self dispatch, stop sequencing, and whether or not drivers should manually depart when starting a route.

Route settings

When creating routes, the API accepts settings for handling route stop arrival and completion. See the section about creating routes for specifics.

Route start and completion settings

Samsara lets you control how and when your routes are marked as started and completed. You can set these conditions at the organization-wide level (in Dispatch Settings on the Dashboard) and for individual routes.

• For an organization-wide default, see the Dispatch Settings knowledge base article.
• For details on route configuration and tracking windows, see the Routes Overview article.

routeStartingCondition

This setting determines how the route’s start time is triggered.

• arriveFirstStop: The route starts when the driver arrives at the first stop.
• departFirstStop (default): The route starts when the driver departs the first stop.

routeCompletionCondition

This setting determines how the route’s completion time is triggered.

• arriveLastStop (default): The route completes when the driver arrives at the last stop.
• departLastStop: The route completes when the driver departs the last stop.

Example end-to-end flow

1. Create an addresses for all major customer locations in Samsara.
2. Create a route referencing those addresses.
3. Assign the route to a driver (or vehicle).
4. As the driver moves, Samsara automatically updates the route's progress.
5. Poll /fleet/routes/audit-logs/feed or subscribe to webhooks to see arrivals, departures, or skipped stops.
6. Update the route if the load changes (add stops, change times, reassign driver).
7. Complete the route automatically (or on driver departure from the last stop, depending on your settings).

---

Next Steps

• For deeper addresses how-to, see the Addresses API Guide.
• For real-time location data, see GPS Tracking for TMS Integrations.
• If you need to automate trailer or shipping ID assignments, check out Carrier Proposed Assignments.