Creating a Route

Create a route with assigned drivers, registered addresses, single-use stop locations, and route settings.

This recipe creates a route with two stops. The first stop uses a registered address by external ID, and the second stop uses a one-time latitude, longitude, and street address.

cURL

curl --request POST "https://api.samsara.com/fleet/routes" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $SAMSARA_API_TOKEN" \
  --data-raw '{
    "externalIds": {
      "routePlanningSystem": "route1234"
    },
    "name": "Route 1234",
    "notes": "Phone number: 1234567890\n\nOrder Info:\n\t- SKU #: 1234567890\n\t- Number of cubes: 2",
    "driverId": "1654973",
    "stops": [
      {
        "externalIds": {
          "routePlanningSystem": "stop1234"
        },
        "addressId": "routePlanningSystem:address1234",
        "scheduledDepartureTime": "2021-05-07T14:30:00Z"
      },
      {
        "externalIds": {
          "routePlanningSystem": "stop5678"
        },
        "name": "Order 1234",
        "notes": "Gate code: 1234\nPhone number: 1234567890\n\nOrder Info:\n\t- SKU #: 1234567890\n\t- Number of cubes: 2",
        "singleUseLocation": {
          "latitude": 37.76865129999999,
          "longitude": -122.4048058,
          "address": "1990 Alameda St, San Francisco, CA 94103, USA"
        },
        "scheduledArrivalTime": "2021-05-07T15:00:00Z"
      }
    ],
    "settings": {
      "routeStartingCondition": "departFirstStop",
      "routeCompletionCondition": "arriveLastStop"
    }
  }'

How it works

1. Call POST /fleet/routes

   The REST API endpoint for creating routes is POST https://api.samsara.com/fleet/routes.

2. Authorize the request

   Include your API access token in the Authorization header using the Bearer token format.

3. Set the route name

   The route name is required. Route names are not unique and can be changed later by Fleet Admins or through the API.

4. Assign the route

   Assign the route with either driverId or vehicleId. These fields are mutually exclusive. If both are omitted, the route is unassigned.

5. Define route stops

   A route must include at least two stops.

6. Choose stop locations

   Each stop needs a location. Use addressId for a registered Address, or use singleUseLocation for a one-time location.

7. Use external IDs for addresses

   The addressId field can use External ID notation in the form idKey:idValue, such as routePlanningSystem:address1234.

8. Configure route settings

   Use settings.routeStartingCondition and settings.routeCompletionCondition to customize when the route starts and completes.

Example response

{
  "data": {
    "id": "4319669712",
    "driver": {
      "id": "1654973",
      "name": "Tyler Freckmann",
      "externalIds": {
        "routePlanningSystem": "driver1234"
      }
    },
    "name": "Route 1234",
    "externalIds": {
      "routePlanningSystem": "route1234"
    },
    "settings": {
      "routeStartingCondition": "departFirstStop",
      "routeCompletionCondition": "arriveLastStop"
    },
    "stops": [
      {
        "id": "4439906042",
        "externalIds": {
          "routePlanningSystem": "stop1234"
        },
        "scheduledDepartureTime": "2021-05-07T14:30:00.000Z",
        "address": {
          "id": "21275762",
          "name": "Home",
          "externalIds": {
            "routePlanningSystem": "address1234"
          }
        },
        "name": "Home",
        "state": "scheduled"
      },
      {
        "id": "4439906043",
        "externalIds": {
          "routePlanningSystem": "stop5678"
        },
        "scheduledArrivalTime": "2021-05-07T15:00:00.000Z",
        "singleUseLocation": {
          "address": "1990 Alameda St, San Francisco, CA 94103, USA",
          "latitude": 37.76865129999999,
          "longitude": -122.4048058
        },
        "name": "Order 1234",
        "state": "scheduled"
      }
    ],
    "scheduledRouteStartTime": "2021-05-07T14:30:00.000Z",
    "scheduledRouteEndTime": "2021-05-07T15:00:00.000Z"
  }
}