Request Methods

The Samsara API endpoints use HTTP request methods. The documentation for each endpoint details what the request method will do, but here are the general patterns:

• GET retrieves data.
• POST creates new objects.
• PATCH updates existing objects. You only need to supply the fields you wish to update. (I.e., no fields are explicitly required, only the ones you wish to update.)
• DELETE deletes objects.
• PUT is only used in rare cases. It replaces the data of an object with new data that you provide - usually in the same structure as a POST request. The object will still have the same ID. To modify some of an object's data, rather than replace it, use PATCH.

🚧

PATCH vs PUT

Most of our APIs use the PATCH method to update objects. In order to use this method, you only need to provide the fields you wish to update. For example, to update a vehicle's name, you would only include the vehicle's name in the request body:

JSON

{
  "name": "New Name"
}

A few of our APIs use the PUT method to update objects. The PUT method replaces the object you are trying to update with the data you provide. This means you must provide a full representation of the object you wish to update. The suggested approach for using the PUT method is to first GET the object you want to update (to retrieve a full representation of it), then modify the fields you wish to update. The object will continue to have the same ID.

For example, to add a stop to a route, you must include all of the route's existing data in the request along with the new stop:

JSON

{
  "id": 1234,
  "name": "Route A",
  "scheduled_start_ms": 1234567890,
  "start_location_address_id": 5678,
  "dispatch_jobs": [
    {
      "destination_address_id": 9012,
      "scheduled_arrival_time_ms": 1234568888,
    },
    {
      "destination_address_id": 3456,
      "destination_address_name": "New Stop",
      "scheduled_arrival_time_ms": 1234569999,
    }
  ]
}