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.

Rate limit: 100 requests/min (learn more about rate limits here).

To use this endpoint, select Write Routes under the Driver Workflow category when creating or editing an API token. Learn More.

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team.

PATCH /fleet/routes/{id}

Update a route

cURL

curl --request PATCH \
  --url https://api.samsara.com/fleet/routes/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "driverId": "1234",
  "externalIds": {},
  "name": "Bid 123",
  "notes": "These are my notes",
  "recomputeScheduledTimes": true,
  "settings": {
    "routeCompletionCondition": "arriveLastStop",
    "routeStartingCondition": "departFirstStop",
    "sequencingMethod": "scheduledArrivalTime"
  },
  "stops": [
    {
      "addressId": "45934",
      "externalIds": {},
      "id": "4125",
      "name": "Stop #1",
      "notes": "These are my notes",
      "ontimeWindowAfterArrivalMs": 300000,
      "ontimeWindowBeforeArrivalMs": 300000,
      "scheduledArrivalTime": "2019-06-13T19:08:25Z",
      "scheduledDepartureTime": "2019-06-13T19:08:25Z",
      "sequenceNumber": 10
    }
  ],
  "tagIds": [
    "123",
    "321"
  ],
  "vehicleId": "453546"
}
'

200

{
  "data": {
    "id": "342341",
    "actualRouteEndTime": "2019-06-13T19:08:25Z",
    "actualRouteStartTime": "2019-06-13T19:08:25Z",
    "driver": {
      "id": "45646",
      "externalIds": {},
      "name": "Driver Bob"
    },
    "externalIds": {},
    "name": "Bid 123",
    "notes": "These are my notes",
    "orgLocalTimezone": "America/Los_Angeles",
    "recurringRouteLiveSharingLinks": [
      {
        "liveSharingUrl": "https://cloud.samsara.com/o/123456/fleet/viewer/address/gEAitEnnOwcv92cuPzcU",
        "name": "Name",
        "expiresAtTime": "2020-01-27T07:06:25Z"
      }
    ],
    "scheduledRouteEndTime": "2019-06-13T19:08:25Z",
    "scheduledRouteStartTime": "2019-06-13T19:08:25Z",
    "settings": {
      "routeCompletionCondition": "arriveLastStop",
      "routeStartingCondition": "departFirstStop",
      "sequencingMethod": "scheduledArrivalTime"
    },
    "stops": [
      {
        "id": "324231",
        "name": "Stop #1",
        "state": "scheduled",
        "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",
          "externalIds": {}
        },
        "documents": [
          {
            "id": "494123",
            "name": "Fuel Receipt Wichita"
          }
        ],
        "enRouteTime": "2006-01-02T15:04:05+07:00",
        "eta": "2006-01-02T15:04:05+07:00",
        "externalIds": {},
        "forms": [
          {
            "id": "41234"
          }
        ],
        "issues": [
          {
            "id": "32812"
          }
        ],
        "liveSharingUrl": "https://cloud.samsara.com/fleet/viewer/job/fleet_viewer_token",
        "locationLiveSharingLinks": [
          {
            "liveSharingUrl": "https://cloud.samsara.com/o/123456/fleet/viewer/address/gEAitEnnOwcv92cuPzcU",
            "name": "Name",
            "expiresAtTime": "2020-01-27T07:06:25Z"
          }
        ],
        "notes": "These are my notes",
        "ontimeWindowAfterArrivalMs": 300000,
        "ontimeWindowBeforeArrivalMs": 300000,
        "plannedDistanceMeters": 5200,
        "scheduledArrivalTime": "2019-06-13T19:08:25Z",
        "scheduledDepartureTime": "2019-06-13T19:08:25Z",
        "sequenceNumber": 10,
        "singleUseLocation": {
          "latitude": 123.456,
          "longitude": 37.459,
          "address": "1234 Main St, San Jose, CA",
          "radiusMeters": 100
        },
        "skippedTime": "2006-01-02T15:04:05+07:00"
      }
    ],
    "tagIds": [
      "123",
      "321"
    ],
    "vehicle": {
      "externalIds": {},
      "id": "494123",
      "name": "Fleet Truck #1"
    }
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id · string · 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

Body

application/json

driverId · string

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

Example:

"1234"

externalIds · object

A map of external ids

Show child attributes

name · string

Name for the route

Example:

"Bid 123"

notes · string

Notes about the route.

Maximum string length: 2000

Example:

"These are my notes"

recomputeScheduledTimes · boolean

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.

Example:

true

settings · object

An optional dictionary, only necessary to override the defaults for route start and end conditions.

Show child attributes

stops · object[]

List of stops along the route. If a valid id of a stop is provided, that stop will be updated. If no id is provided for a passed in stop, that stop will be created. If id value are passed in for some stops and not for others, those with id value specified will be retained and updated in the original route, those without id value specified in the body will be created, and those without id value specified that already existed on the route will be deleted. For each new stop, exactly one of addressId and singleUseLocation are required. Depending on the settings on your route, either a scheduledArrivalTime or scheduledDepartureTime must be specified for the first job, if a new first job is being added.

Show child attributes

tagIds · string[]

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

Example:

["123", "321"]

vehicleId · string

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

Example:

"453546"

Response

200

application/json

OK response.

data · object

Show child attributes