Overview

This page will describe how to:

• Create a basic route.
• Assign a route to a driver or vehicle.
• Adjust the route starting and completion settings for your use case.
• Provide route stop instructions via notes.
• Utilize external IDs to help sync with an external system.

A Basic Route

The minimum requirements for any route are:

• A route name.
• At least two stops that must include
  • An address or single-use location. (See Stop Locations).
  • A scheduled arrival/departure time.

Let’s look at the simple request for creating a very 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",
    "stops": [
        {
            "addressId": "12086521",
            "scheduledDepartureTime": "2021-05-07T14:30:00Z"
        },
        {
            "addressId": "21275794",
            "scheduledArrivalTime": "2021-05-07T15:00:00Z"
        }
    ]
}'

This example uses Addresses to assign the stops' locations. See the Stop Locations guide for details.

This route is currently unassigned. To see how to assign a route, read on below.

Assigning a Route

To assign a route to a driver or vehicle, you would either include the driverId or vehicleId field in the request:

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": "2021-05-07T14:30:00Z"
        },
        {
            "addressId": "21275794",
            "scheduledArrivalTime": "2021-05-07T15:00:00Z"
        }
    ]
}'

A route can be assigned to either a driver or a vehicle but not to both.

You can assign a route to a vehicle by replacing the driverId field above with vehicleId.

If neither the driverId nor vehicleId field is assigned, the route will be unassigned. You can assign it later by Updating the Route.

Route Starting and Completion Settings

You can customize the automatic tracking of your route start time and completion time in two ways:

• Setting the route's starting condition
• Setting the route's completion condition

This is controlled by the settings field of the route. The default settings for a route are:

{
    "settings": {
        "routeStartingCondition": "departFirstStop",
        "routeCompletionCondition": "arriveLastStop"
    }
}

This means that, by default, the route will start when the vehicle departs from the first stop, and the route will complete when the vehicle arrives at the last stop.

You can adjust these settings to fit your use case:

• routeStartingCondition: Valid values: departFirstStop, arriveFirstStop
• routeCompletionCondition: Valid values: arriveLastStop, departLastStop

Stop Arrival/Departure Times

If the routeStartingCondition is set to departFirstStop (this is the default mode), then the first stop must have a scheduledDepartureTime. If it is set to arriveFirstStop, then it must have a scheduledArrivalTime.

If the routeCompletionCondition is set to arriveLastStop (this is the default mode), then the last stop must have a scheduledArrivalTime. If it is set to departLastStop, then it must have a scheduledDepartureTime.

All other stops must have a scheduledArrivalTime. The scheduledDepartureTime is optional, and, if omitted, will be automatically set to the next stop's scheduledArrivalTime.

Stops are automatically ordered by their scheduled arrival times. It does not matter which order you place them in the array, Samsara will always order them by their scheduled arrival times.

📘Timestamps

See the Timestamps guide for details on working with timestamps.

Route Stop Instructions

You can use the notes field on the route and/or each route stop in order to give instructions to the driver. These fields can contain general information such as gate codes or phone numbers, and they can also contain information about the order such as weight, cubes, SKUs.

The notes fields can be formatted using newline characters: /n and tabs: /t.

Let's say you want to include the following route stop note:

Gate code: 12345
Phone number: 1234567890

Order Info:
	- SKU #: 1234567890
	- Number of cubes: 2

You would replace all newline and tab characters with \n and \t in the string that you provide to the notes field as part of your request:

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": "2021-05-07T14:30:00Z"
        },
        {
            "addressId": "21275794",
            "scheduledArrivalTime": "2021-05-07T15:00:00Z",
            "notes": "Gate code: 12345\nPhone number: 1234567890\n\nOrder Info:\n\t- SKU #: 1234567890\n\t- Number of cubes: 2"
        }
    ]
}'

This is how the note will appear in the Samsara Driver App:

📘

Route Stop Tasks

See Creating Stop Tasks to learn how to create interactive driver tasks using Samsara's Documents feature.

(The notes field described above is only meant for static instructions).

External IDs

You can use External IDs on routes, stops, and addresses in order to help sync with an external system.

The following example creates an external ID for the route and for each of its stops, and it also defines the location for route stops by referring to address external IDs:

curl --request POST 'https://api.samsara.com/fleet/routes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<token>>' \
--data-raw '{
    "name": "Route 1234",
    "externalIds": {
        "routePlanningSystem": "route1234"
    },
    "stops": [
        {
            "externalIds": {
                "routePlanningSystem": "stop1234"
            },
            "addressId": "routePlanningSystem:address1234",
            "scheduledDepartureTime": "2021-05-07T14:30:00Z"
        },
        {
            "externalIds": {
                "routePlanningSystem": "stop4567"
            },
            "addressId": "routePlanningSystem:address4567",
            "scheduledArrivalTime": "2021-05-07T15:00:00Z"
        }
    ]
}'

(Note: external IDs must be unique if they share the same key).