SAsamsara
Routes

Create a route

Create a route. The legacy version of this endpoint can be found at samsara.com/api-legacy.

<b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select Write Routes under the Driver Workflow category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

post/fleet/routes

Request

  • Base URL
    https://api.samsara.com
  • Auth
    HTTP bearer

Request body

driverIdstring

ID of the driver. Can be either a unique Samsara ID or an external ID for the driver.

externalIdsobject

A map of external ids

namestring required

Name for the route

notesstring

Notes about the route.

recomputeScheduledTimesboolean

This optional boolean parameter controls whether route schedule arrival and departure times are recalculated. When set to true, the system will automatically recompute the scheduledArrivalTime and scheduledDepartureTime for each stop along the route during route creation. This process overrides any manually provided values, with the exception of the first stop, which retains its user-defined schedule.

tagIdsstring[]

An array of IDs of tags to associate with this route.

vehicleIdstring

ID of the vehicle. Can be either a unique Samsara ID or an external ID for the vehicle.

Example request

{
  "driverId": "1234",
  "name": "Bid 123",
  "notes": "These are my notes",
  "recomputeScheduledTimes": true,
  "settings": {
    "routeCompletionCondition": "arriveLastStop",
    "routeStartingCondition": "departFirstStop",
    "sequencingMethod": "scheduledArrivalTime"
  },
  "stops": [
    {
      "addressId": "45934",
      "appointmentWindows": [
        {
          "endTime": "2019-06-13T20:08:25Z",
          "startTime": "2019-06-13T19:08:25Z"
        }
      ],
      "forms": [
        {
          "formTemplateId": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
          "isRequired": true
        }
      ],
      "name": "Stop #1",
      "notes": "These are my notes",
      "ontimeWindowAfterArrivalMs": 300000,
      "ontimeWindowBeforeArrivalMs": 300000,
      "orders": [
        {
          "customerProperties": [
            {
              "key": "purchaseOrderNumber",
              "value": "PO-12345"
            }
          ],
          "externalIds": {
            "tmsOrder": "12345"
          },
          "id": "018f7b62-7d55-7b9e-a92f-2a6b7ff10392",
          "samsaraCustomerOrderName": "Order 12345",
          "tasks": [
            {
              "customerProperties": [
                {
                  "key": "purchaseOrderNumber",
                  "value": "PO-12345"
                }
              ],
              "dispatcherNotes": "Customer requires lift gate",
              "driverNotes": "Use loading dock 4",
              "hubId": "018f7b62-7d55-7b9e-a92f-2a6b7ff10392",
              "id": "12345678",
              "positionConstraintType": "none",
              "quantities": [
                {
                  "capacityId": "018f7b62-7d55-7b9e-a92f-2a6b7ff10392",
                  "label": "pallets",
                  "value": 12
                }
              ],
              "serviceDurationSeconds": 900,
              "serviceLocation": {
                "addressId": "12345678",
                "customAddress": {
                  "addressLine1": "123 Main St",
                  "addressLine2": "Dock 4",
                  "city": "Oakland",
                  "country": "US",
                  "formattedAddress": "123 Main St, Oakland, CA 94607",
                  "latitude": 37.8044,
                  "longitude": -122.2712,
                  "postalCode": "94607",
                  "state": "CA"
                },
                "serviceLocationType": "savedAddress"
              },
              "serviceWindowIdsToRemove": [
                "Numquam ut praesentium veritatis saepe eos.",
                "Voluptatem laudantium provident.",
                "Quaerat facilis autem dolor eum culpa minus.",
                "Consectetur veniam suscipit quam."
              ],
              "serviceWindows": [
                {
                  "endTime": "2026-07-01T11:00:00Z",
                  "id": "018f7b62-7d55-7b9e-a92f-2a6b7ff10392",
                  "startTime": "2026-07-01T09:00:00Z"
                }
              ],
              "taskType": "delivery"
            }
          ]
        }
      ],
      "scheduledArrivalTime": "2019-06-13T19:08:25Z",
      "scheduledDepartureTime": "2019-06-13T19:08:25Z",
      "sequenceNumber": 10,
      "singleUseLocation": {
        "address": "1234 Main St, San Jose, CA",
        "latitude": 123.456,
        "longitude": 37.459,
        "radiusMeters": 100
      }
    }
  ],
  "tagIds": [
    "123",
    "321"
  ],
  "vehicleId": "453546"
}

Response

OK response.

Example response

{
  "data": {
    "actualRouteEndTime": "2019-06-13T19:08:25Z",
    "actualRouteStartTime": "2019-06-13T19:08:25Z",
    "driver": {
      "id": "45646",
      "name": "Driver Bob"
    },
    "id": "342341",
    "name": "Bid 123",
    "notes": "These are my notes",
    "orgLocalTimezone": "America/Los_Angeles",
    "recurringRouteLiveSharingLinks": [
      {
        "expiresAtTime": "2020-01-27T07:06:25Z",
        "liveSharingUrl": "https://cloud.samsara.com/o/123456/fleet/viewer/address/gEAitEnnOwcv92cuPzcU",
        "name": "Name"
      }
    ],
    "scheduledRouteEndTime": "2019-06-13T19:08:25Z",
    "scheduledRouteStartTime": "2019-06-13T19:08:25Z",
    "settings": {
      "routeCompletionCondition": "arriveLastStop",
      "routeStartingCondition": "departFirstStop",
      "sequencingMethod": "scheduledArrivalTime"
    },
    "stops": [
      {
        "actualArrivalTime": "2006-01-02T15:04:05+07:00",
        "actualDepartureTime": "2006-01-02T15:04:05+07:00",
        "actualDistanceMeters": 5450,
        "address": {
          "id": "494123",
          "name": "Company Office #1"
        },
        "appointmentWindows": [
          {
            "endTime": "2019-06-13T20:08:25Z",
            "startTime": "2019-06-13T19:08:25Z"
          }
        ],
        "documents": [
          {
            "id": "494123",
            "name": "Fuel Receipt Wichita"
          }
        ],
        "enRouteTime": "2006-01-02T15:04:05+07:00",
        "eta": "2006-01-02T15:04:05+07:00",
        "forms": [
          {
            "formTemplateId": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
            "id": "41234",
            "isRequired": true
          }
        ],
        "id": "324231",
        "issues": [
          {
            "id": "32812"
          }
        ],
        "liveSharingUrl": "https://cloud.samsara.com/fleet/viewer/job/fleet_viewer_token",
        "locationLiveSharingLinks": [
          {
            "expiresAtTime": "2020-01-27T07:06:25Z",
            "liveSharingUrl": "https://cloud.samsara.com/o/123456/fleet/viewer/address/gEAitEnnOwcv92cuPzcU",
            "name": "Name"
          }
        ],
        "name": "Stop #1",
        "notes": "These are my notes",
        "ontimeWindowAfterArrivalMs": 300000,
        "ontimeWindowBeforeArrivalMs": 300000,
        "orders": [
          {
            "id": "018f7b62-7d55-7b9e-a92f-2a6b7ff10392",
            "taskId": "12345678"
          }
        ],
        "plannedDistanceMeters": 5200,
        "scheduledArrivalTime": "2019-06-13T19:08:25Z",
        "scheduledDepartureTime": "2019-06-13T19:08:25Z",
        "sequenceNumber": 10,
        "singleUseLocation": {
          "address": "1234 Main St, San Jose, CA",
          "latitude": 123.456,
          "longitude": 37.459,
          "radiusMeters": 100
        },
        "skippedTime": "2006-01-02T15:04:05+07:00",
        "state": "scheduled"
      }
    ],
    "tagIds": [
      "123",
      "321"
    ],
    "vehicle": {
      "id": "494123",
      "name": "Fleet Truck #1"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.