Samsara Developer Portal

Integrate your data with the Samsara API, customize the Samsara experience, and join a community of developers building with Samsara.

Get Started

Common Patterns

Reference guide for common ways of accessing and exchanging data with Samsara

The Samsara API is a RESTful API. It uses standard HTTP authentication, verbs, and response codes, and it returns JSON response bodies. If you're familiar with what you can build with a REST API, then this will be your go-to API reference.

If you have any questions, reach out to us at [email protected].

Endpoints

You can access all our APIs through HTTP requests to URLs like:

https://api.samsara.com/<endpoint>

For EU customers, this URL will be:

https://api.eu.samsara.com/<endpoint>

Legacy endpoints will have the URL: https://api.samsara.com/v1/<endpoint> or https://api.eu.samsara.com/v1/<endpoint>

Authentication

To authenticate your API request, you will need to include your secret token. You can manage your API tokens in the Dashboard. They are visible under "Settings" -> "Developer" -> "API Tokens".

Your API tokens carry many privileges, so be sure to keep them secure. Do not share your secret API tokens in publicly accessible areas such as GitHub, client-side code, and so on.

You authenticate to the API via Bearer Token in the HTTP Authorization header. Provide your API token as the access_token value in an Authorization: Bearer header. You do not need to provide a password:

Authorization: Bearer {access_token}

The API uses HTTPS. Calls made over plain HTTP or without authentication will fail.

Request Methods

Our 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 versus 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:

{
  "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:

{
  "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,
    }
  ]
}

Response Codes

All API requests will respond with an appropriate HTTP status code.

Your API client should handle each response class differently:

  • 2XX codes are successful responses.
  • 4XX codes are client error responses, meaning there was an error with the way the request was submitted, such as a missing parameter or invalid value. You should modify requests before retrying.
  • 5XX codes are server error responses. There may be a temporary issue on the Samsara side, so you may want to retry after some delay. Please use exponential backoff as a retry model - see here for an example algorithm.

Error Codes

Here is a table of error codes that may help you debug. The error response body may include an error message, but do not hard-code against this message. We reserve the right to change the error message without auto-incrementing the API version. Only use error messages for debugging purposes.

Status Code
Description

400

Bad Request - General client error, possibly malformed data.

401

Unauthenticated - The API key is missing or invalid.

404

Not Found - The API endpoint being accessed is invalid, a path parameter is missing or invalid (e.g. id in /fleet/drivers/{id})), or you do not have access to this resource. You may expect to see a 403 in these cases, but we do not want to provide any information about resources if you do not have access to them.

405

Method Not Allowed - The API endpoint does not accept that HTTP method.

429

Too Many Requests - The client has reached or exceeded a rate limit, or the server is overloaded. Retry using exponential backoff. See Rate Limiting.

5XX

Internal Server errors - something went wrong with Samsara's servers. These responses are likely momentary errors (e.g., temporary unavailability), and as a result, requests should be retried using exponential backoff. Note that the body of these responses will be strings and not JSON encoded.

Rate Limiting

API Rate Limits are in place to protect Samsara from API traffic spikes that could put our services at risk. We, therefore, measure the number of requests sent to the API in order to throttle these when they surpass the amount allowed. We will respond with an HTTP error code of 429 when rate limits exceed those described below.

Per-token rate limits for public APIs (requests per access token per second)

150

Per-org rate limits for public APIs (requests per org per second)

200

We will also respond with the following header on 429 responses:

Header Name
Header Description

Retry-After

Suggested time to wait before retrying (in seconds). Example: 0.40235

Versioning

If a breaking change is necessary for the API, we will release a new dated-version. You can access new versions by upgrading your API token. We do not plan on releasing breaking changes unless it is necessary (e.g., for support or security reasons). New features will not cause breaking changes, and you can immediately take advantage of them for both new or legacy endpoints.

Examples of breaking changes include:

  • Adding a mandatory request parameter to existing API methods
  • Removing properties from existing API responses

Non-breaking changes will be accessible across all versions of the API. Examples of these include:

  • Adding new API resources
  • Adding new optional request parameters to existing API methods
  • Adding new properties to existing API responses
  • Changing the order of properties in existing API responses
  • Changing the length or format of object IDs or other opaque strings

Version Header

API tokens are associated with a given dated version, e.g. 2019-12-12, etc. You can view and upgrade the versions of API tokens on the API token page of the Samsara Dashboard.

You can override the version of your API token by providing an X-Samsara-Version HTTP header with your request:

GET /fleet/vehicles/locations HTTP/1.1
Host: api.samsara.com
X-Samsara-Version: 2018-01-01
Authorization: Bearer <token>

The above will override the request to use the 2018-01-01 version of the endpoint regardless of the version the API token is associated with.

Pagination

Endpoints that GET a collection are paginated. To work with paginated endpoints, do the following:

  1. On submission of the first request, you can optionally provide a limit parameter to limit the number of objects returned in the first page. The default and max is 512.
curl -X GET \
  'https://api.samsara.com/fleet/vehicles?limit=5' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'
{
  "data": [ ... ],
  "pagination": {
    "endCursor": "MjkY",
    "hasNextPage": true
  }
}
  1. The response contains a data array and a pagination object. The data array will include the first page of data. If hasNextPage is true, use the endCursor to request the next page of data by providing it as the after parameter in your subsequent request.
curl -X GET \
  'https://api.samsara.com/fleet/vehicles?limit=5&after=MjkY' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'
  1. Continue using the above pattern until you hasNextPage is false.

Cursor Expiration

Cursors expire after 30 days.

Some endpoints on the legacy API use slightly different names for pagination.

Timestamps

Timestamps use RFC 3339 format. Millisecond precision and timezones are supported.

Examples:

  • 2019-06-13T19:08:25Z
  • With millisenconds: 2019-06-13T19:08:25.455Z
  • With timezone: 2015-09-15T14:00:12-04:00

The legacy API uses unix epoch millisecond timestamps.

Mini-objects

Frequently, when one object is related to another, such as a driver's vehicle or an address's contact, the response body of that object will contain a "mini-object" referencing the object it's related to.

{
  "data": {
    "currentVehicle": {
      "id": "123456789",
      "name": "Midwest Truck #4"
  },
  ...
}

In the above example, the driver response contains a mini-object of the driver's current vehicle.

Filtering

You can optionally filter by tags when listing a collection of objects, such as with GET /fleet/vehicles.

You can also filter by specific objects when retrieving time-series data, such as with the GET /fleet/vehicles/locations endpoints.

To filter by tags, supply a comma-separated list of desired tag IDs in the tagIds query parameter. This will list all objects in any of the supplied tags. (An OR operation on tagIds).

For example,

curl -X GET \
  'https://api.samsara.com/fleet/vehicles?tagIds=55371,25956' \
  -H 'Authorization: Bearer <token>'

will list all the vehicles in either of the supplied tags (55371 or 25956).

To filter time-series data by object IDs, the same logic is applied. You can supply a comma-separated list of desired object IDs in the designated field. This will provide location data for any of the listed objects.

For example,

curl -X GET \
  'https://api.samsara.com/fleet/vehicles/locations?vehicleIds=212014918234495,212014918481595' \
  -H 'Authorization: Bearer <token>'

will list location data for either of the vehicle IDs provided.

Filtering by both tags and object IDs will result in data from objects in both the object ID list and the provided tag list. (e.g., IN tagIds AND IN vehicleIds)

External IDs

External IDs allow you to reference Samsara objects using a custom ID field, set by you. This is currently only available for drivers, vehicles, and addresses.

External IDs consist of key-value pairs, where the key is the name of the ID and the value is the unique identifier for that object. For example, you could have a payroll external ID and a maintenance external ID, and each object will have a unique value for each of those IDs. External IDs are represented as dictionaries for their respective objects:

{
  "externalIDs" : {
    "payroll": "ABCD",
    "maintenance": "1234"
  }
}

Currently, you can only set external IDs when creating or updating objects via the API. To set an external ID, use either the POST or PATCH method for the given object and include a dictionary of external ID key-value pairs. For example:

curl -X PATCH \
  https://api.samsara.com/fleet/drivers/{id} \
  -H 'Authorization: Bearer <token>' \
  -d '{
        "externalIds": {
    	    "maintenance": "1234"
        }
      }'

The above example will add an external ID key-value pair of maintenance:1234 to the driver object referenced by {id} in the path.

Both the keys and the values of the dictionary are of type string and must be alphanumeric. Each organization can have at most 10 unique external ID keys. For example, payroll and maintenance would count as two external ID keys for my organization. To delete an external ID from an object, set its value to null or the empty string (""). For example: "maintenance": null or "maintenance": "".

To retrieve or update an object by its external ID, include it in the path of the request using the following syntax: key:value. For example, the following would reference the driver from the above example.

https://api.samsara.com/fleet/drivers/maintenance:1234

Updated 6 days ago



Common Patterns


Reference guide for common ways of accessing and exchanging data with Samsara

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.