Guides
SUPPORTFEEDBACK

Routing

Integrate route creation, assignment, and progress tracking with your TMS.

Suggest Edits

Samsara refers to loads as routes. A route is a planned sequence of stops assigned to either a vehicle or a driver.

Overview

  • Automated Load Assignment Automatically push loads (routes) from your TMS into Samsara so drivers see them in the Samsara Driver App.

  • Real-Time Progress Tracking Samsara's Vehicle Gateways automatically track ETA, arrival, departure, and route completion times, giving dispatchers continuous visibility.

  • Driver Workflow Drivers can see route stops, notes or instructions, and use forms to capture key documents (e.g., proof of delivery).

  • Seamless Two-Way Sync Keep your TMS and Samsara updated whenever a stop is added, removed, or changed.

Key concepts

  1. Routes vs. Loads

    • In Samsara, each “route” can represent an entire load or multiple shipments.
    • A route must have at least two stops (e.g., pickup and drop-off).

  2. Assigning Routes

    • Routes can be created with out any assignment.
    • Routes can be assigned to only one of the following:
      • A driver (recommended if the driver remains with the load)
      • A vehicle (recommended if the vehicle remains the same but drivers might change)

  3. Stops & Addresses

    • Each route has multiple stops.
    • Stops can reference reusable Addresses (preferred) or single-use lat/long.
    • Use notes or scheduled times to inform drivers of instructions, delivery windows, etc.

  4. Automatic Tracking

    • Samsara uses GPS location and geofences to track each route stop's en route, arrived, departed, or skipped states.

  5. Route Completion Settings

    • Control how routes “start” or “end” automatically (e.g., on arrival vs. departure of a stop).

Orders (Represented as Stop Notes)

Samsara does not have a first-class “Order” object. 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.

  • Most TMS systems model loads or shipments as a series of orders, each tied to a pickup and/or delivery location.
  • In Samsara, stops are the anchor points for location-based activity — so attaching order info to a stop gives drivers the full context they need at that location.
  • Notes are shown to drivers in the Samsara Driver App at the relevant stop.

Example

{
  "addressId": "21275794",
  "scheduledArrivalTime": "2024-06-13T20:15:00Z",
  "notes": "Gate code: 12345\nPhone: 1234567890\n\nOrder Info:\n  - SKU: 123456\n  - PO: 98765"
}

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.


1. Creating routes

Basic Requirements

  • Route Name – Unique label for the load (e.g., “Load #1234”).
  • At Least Two Stops – For pickup and drop-off (or multiple stops if needed).
  • Stop Location – Typically an Address ID or a single-use lat/long.
  • Scheduled Arrival/Departure Times – Let Samsara plan arrival/departure tracking.

Example request to create a basic route

curl --request POST 'https://api.samsara.com/fleet/routes' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>>' \
     --data-raw '{
       "name": "Route 1234",
       "driverId": "1654973",
       "stops": [
         {
           "addressId": "12086521",
           "scheduledDepartureTime": "2024-06-13T19:08:25Z"
         },
         {
           "addressId": "21275794",
           "scheduledArrivalTime": "2024-06-13T20:15:00Z"
         }
       ]
     }'
  • driverId: Assigns this route to the driver with ID 1654973.
  • stops: Each stop references an existing address by ID. (See Addresses API.)
  • scheduledArrivalTime / scheduledDepartureTime: Timestamps that Samsara uses for route planning.

Example response

{
    "data": {
        "id": "6026627437",
        "driver": {
            "id": "1654973",
            "name": "Test Driver",
        },
        "name": "Route 1234",
        "stops": [
            {
                "id": "6171822365",
                "scheduledDepartureTime": "2025-03-01T00:01:00.000Z",
                "notes": "",
                "address": {
                    "id": "12086521",
                    "name": "HQ"
                },
                "name": "HQ",
                "state": "scheduled",
                "liveSharingUrl": "https://cloud.samsara.com/o/0/fleet/viewer/job/HC723VbW5igMjLPlG5pg"
            },
            {
                "id": "6171822366",
                "scheduledArrivalTime": "2025-03-01T00:03:00.000Z",
                "notes": "",
                "address": {
                    "id": "21275794",
                    "name": "Bus"
                },
                "name": "Bus",
                "state": "scheduled",
                "liveSharingUrl": "https://cloud.samsara.com/o/0/fleet/viewer/job/Bkei0un0zSWsODqhtB76"
            }
        ],
        "scheduledRouteStartTime": "2025-03-01T00:01:00.000Z",
        "scheduledRouteEndTime": "2025-03-01T00:03:00.000Z"
    }
}

Route settings

You can control start and completion conditions with the settings field:

"settings": {
  "routeStartingCondition": "departFirstStop",
  "routeCompletionCondition": "arriveLastStop"
}
  • routeStartingCondition can be departFirstStop or arriveFirstStop.
  • routeCompletionCondition can be arriveLastStop or departLastStop.

By default, departFirstStop and arriveLastStop are used.

2. Managing stop details

Stop notes and instructions

Use the notes field to pass important information to drivers like gate codes, contact phone, or order details. Samsara does not have a concept of an Order and instead you can add any order details to the free-form notes section of each stop.

{
  "addressId": "21275794",
  "scheduledArrivalTime": "2024-06-13T20:15:00Z",
  "notes": "Gate code: 12345\nPhone: 1234567890\n\nOrder Info:\n\t- SKU: 123456"
}

Drivers can see these notes in the Samsara Driver App.

Single-use locations vs. addresses

  • Addresses – Reusable locations with geofences that are managed with the Addresses API.
  • Single-Use – Ad-hoc lat/long passed inline with singleUseLocation.

Recommendation: Use Addresses for better geocoding, reporting, and reusability.

3. Updating Existing Routes

Routes often change—stops get added or removed, schedules shift, or a new driver is assigned.

  • The PATCH /fleet/routes/:id endpoint requires the entire updated stops array. Sending a patch request with only the stops array (and no other route params) works well to manage stops related to a route.
  • Retain Stop IDs: If you want to keep an existing stop, make sure to include its id in your updated list. Otherwise, Samsara treats it as removed.

Example request to add a stop

curl --location --request PATCH 'https://api.samsara.com/fleet/routes/6026627437' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: <token>' \
--data '{
    "stops": [
        {
            "id": "6171822365",
            "scheduledDepartureTime": "2025-03-01T00:01:00.000Z",
            "notes": "",
            "address": {
                "id": "12086521",
                "name": "HQ"
            },
            "name": "HQ",
            "state": "scheduled",
            "liveSharingUrl": "https://cloud.samsara.com/o/0/fleet/viewer/job/HC723VbW5igMjLPlG5pg"
        },
        {
            "id": "6171822366",
            "scheduledArrivalTime": "2025-03-01T00:03:00.000Z",
            "notes": "",
            "address": {
                "id": "21275794",
                "name": "Bus"
            },
            "name": "Bus",
            "state": "scheduled",
            "liveSharingUrl": "https://cloud.samsara.com/o/0/fleet/viewer/job/Bkei0un0zSWsODqhtB76"
        },
        {
            "addressId": "232149339",
            "scheduledArrivalTime": "2025-03-01T00:10:00.000Z"
        }
    ]
}'

import requests, json

url = "https://api.samsara.com/fleet/routes/6026627437"
headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

# Get current route data
route = requests.get(url, headers=headers).json()
stops = route["data"]["stops"]

# Add a new stop
stops.append({
  "addressId": "21275762",
  "scheduledArrivalTime": "2024-06-13T21:00:00Z"
})

# Send PATCH request
payload = { "stops": stops }
response = requests.patch(url, headers=headers, data=json.dumps(payload))

4. Tracking route progress

Polling: route audit logs feed

Use GET /fleet/routes/audit-logs/feed to poll for updates (stop arrivals, departures, skip events). Each call returns:

  • operation: e.g. "stop arrived", "stop en route", "stop skipped".
  • changes.before / changes.after: The state of each stop.
  • Pagination via endCursor: Pass ?after=<previousEndCursor> to get new updates since your last call.
curl --request GET 'https://api.samsara.com/fleet/routes/audit-logs/feed?after=<cursor>' \
     --header 'Authorization: Bearer <token>'

Webhooks: RouteStopArrival & RouteStopDeparture

For event-driven workflows, subscribe to the RouteStopArrival or RouteStopDeparture webhooks:

{
  "eventType": "RouteStopArrival",
  "data": {
    "routeStopDetails": {
      "state": "arrived",
      "id": "141414",
      "actualArrivalTime": "2024-06-13T19:15:00Z"
    },
    "route": {
      "id": "342341",
      "externalIds": {
        "myRouteId": "abc"
      },
      "stops": [...]
    },
    "driver": {...}
  }
}

This approach notifies your TMS when a driver arrives/departs a stop.

5. Load and resource assignments

Carrier proposed assignments

If you need to prompt drivers to confirm which trailer or vehicle they’re using, use Carrier Proposed Assignments. This is separate from route assignment but complements load workflows:

  • Propose a trailer or shipping ID to the driver.
  • The driver accepts in the Samsara Driver App.
  • The TMS sees updated driver-trailer association.

Handling Y-splits (T-calls)

Some loads require more than one driver to complete the delivery. This is known as a Y-split or T-call, where a route is split into multiple segments, each assigned to a different driver. Samsara’s Routes API supports both planned and ad hoc Y-splits.

Planned Y-splits

If your TMS knows in advance that multiple drivers will move the load in segments, you can create multiple routes from the start—one for each driver—with stops representing their portion of the load.

Example flow:

  1. Create Route 1 for Driver A (first leg)
  2. Create Route 2 for Driver B (second leg)
  3. Optionally, use notes or external IDs to correlate the two segments as part of a single load

Example request to create Route 1 (first leg):

curl -X POST 'https://api.samsara.com/fleet/routes' \
--header "Authorization: Bearer <TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "name": "Load #9876 - Leg 1",
  "driverId": "123456",
  "stops": [
    {
      "addressId": "10001",
      "scheduledDepartureTime": "2025-03-25T13:00:00Z"
    },
    {
      "addressId": "10002",
      "scheduledArrivalTime": "2025-03-25T15:00:00Z"
    }
  ]
}'

Example request to create Route 2 (second leg):

curl -X POST 'https://api.samsara.com/fleet/routes' \
--header "Authorization: Bearer <TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "name": "Load #9876 - Leg 2",
  "driverId": "654321",
  "stops": [
    {
      "addressId": "10002",
      "scheduledDepartureTime": "2025-03-25T15:30:00Z"
    },
    {
      "addressId": "10003",
      "scheduledArrivalTime": "2025-03-25T18:00:00Z"
    }
  ]
}'

In this example, both routes share the transfer point stop (addressId: 10002), with a handoff between Driver A and Driver B.

Ad-hoc Y-splits

Sometimes, Y-splits are unplanned and happen during execution (e.g., due to a breakdown, hours-of-service limit, or unexpected dispatch change). You can split a route mid-route using the following process:

Step-by-step:

  1. Edit the original route using PATCH /fleet/routes/:id to remove stops no longer assigned to the original driver.
  2. Create a new route using POST /fleet/routes, starting from the handoff point and assigned to the next driver.

Example: Ad hoc split at second stop

Original route (before split):

Stop 1 → Stop 2 → Stop 3
Driver A

After Y-split:

  • Driver A completes Stop 1 and Stop 2.
  • Driver B picks up from Stop 3.

1. Update the original route to end at Stop 2:

curl -X PATCH 'https://api.samsara.com/fleet/routes/ROUTE_ID' \
--header "Authorization: Bearer <TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "stops": [
    {
      "id": "STOP_1_ID"
    },
    {
      "id": "STOP_2_ID"
    }
  ]
}'

2. Create a new route for Driver B from Stop 3:

curl -X POST 'https://api.samsara.com/fleet/routes' \
--header "Authorization: Bearer <TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "name": "Ad hoc leg for Load #9876",
  "driverId": "654321",
  "stops": [
    {
      "addressId": "10003",
      "scheduledArrivalTime": "2025-03-25T18:00:00Z"
    }
  ]
}'

Best practices and tips

  1. Combine GPS + routing

  2. Reference addresses

    • Addresses allow custom geofences, better geocoding, and consistent reuse.
    • Single-use is quick for one-offs but lacks robust reporting and smaller geofence controls.

  3. Check for stop arrival/departure

    • If automatic arrival detection doesn’t suit your workflow (due to large geofences or close stops), you can configure manual arrive/depart in the Samsara Dashboard.

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

Updated about 2 hours ago

What’s Next