Creating Routes

Create and assign routes and configure route start and completion settings.

Learn 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.
• Use external IDs to help sync with an external system.

Create 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, 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 start 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 and departure times

When creating routes, each stop requires a schedule to determine when the vehicle is expected to arrive or depart. The first and last stop of a route are special and depending on the route’s starting and completion conditions the first and last stop may require one of an arrival or departure time.

First stop

WhenrouteStartingCondition is departFirstStop then scheduledDepartureTime is required.

When routeStartingCondition is arriveFirstStopthen scheduledArrivalTime is required.

Last stop

When routeCompletionCondition is arriveLastStop then scheduledArrivalTime is required.

When routeCompletionCondition is departLastStop then scheduledDepartureTime is required.

Intermediate stops

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 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.

By default, Samsara validates that arrival and departure times cannot overlap. This validation can be disabled in organization wide by navigating to Settings > Dispatch.

Timestamps

See the Timestamps guide for details on working with timestamps.

Route Stop Instructions

Use the notes field on the route or each route stop to share instructions with 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 support 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 appears 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 a route with an external ID on the route and stops with external IDs, and it also sets route stop locations using address external IDs (as shown in Stop Locations):

curl --request POST 'https://api.samsara.com/fleet/routes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_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.