SAsamsara
Routes

Update a route

Update a route. Note this implementation of patch uses the JSON merge patch proposed standard. This means that any fields included in the patch request will overwrite fields which exist on the target resource. For arrays, this means any array included in the request will replace the array that exists at the specified path, it will not add to the existing array.

The legacy version of this endpoint (which uses PUT instead of PATCH) 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.

patch/fleet/routes/{id}

Request

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

Path parameters

idstring required

ID of the route. This can either be the Samsara-specified ID, or an external ID. External IDs are customer specified key-value pairs created in the POST or PATCH requests of this resource. To specify an external ID as part of a path parameter, use the following format: key:value. For example, payrollId:ABFS18600

Request body

driverIdstring nullable

ID of the driver. Can be either a unique Samsara ID or an external ID for the driver. Set to null to unassign the driver from the route.

externalIdsobject

A map of external ids

namestring

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 nullable

ID of the vehicle. Can be either a unique Samsara ID or an external ID for the vehicle. Set to null to unassign the vehicle from the route.

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
        }
      ],
      "id": "4125",
      "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.