API docs by Redocly

Samsara Legacy API (2020-06-15)

Download OpenAPI specification:Download

Overview

New API Available! Samsara has launched a **new and improved API!** You can read more about the new API [here](https://developers.samsara.com/docs/introducing-our-next-generation-api).

Samsara provides API endpoints so that you can build powerful applications and custom solutions with sensor data. Samsara has endpoints available to track and analyze sensors, vehicles, and entire fleets.

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, please visit https://samsara.com/help.

Endpoints

All our APIs can be accessed through HTTP requests to URLs like:

https://api.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->Organization->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.

Authentication to the API is performed 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}

All API requests must be made over HTTPS. Calls made over plain HTTP or without authentication will fail.

API tokens now have granular scopes. For more on granular scopes and which scopes are required for our legacy APIs, read here.

Common Patterns

You can find more info about request methods, response codes, error codes, and versioning here.

Fleet

Access to fleet data

/addresses

Fetch all addresses/geofences for the organization. An address contains either a circle or polygon geofence describing the address boundaries.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/addresses

Add one or more addresses to the organization

Request Body schema: application/json

List of addresses/geofences to add. An address must always be provided, and a geofence of either circular or a polygonal type must also always be provided. For circular geofences, lat/long are optional and will be automatically populated through geocoding asynchronously if not provided, but radiusMeters is required. For polygonal geofences, lat/long coordinates are required. For each address, only one of 'circle' or 'polygon' should be provided. If both are provided, the geofence will be saved as a polygon.

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "addresses": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

/addresses/{addressId}

Fetch an address by its id.

path Parameters
addressId
required
integer <int64>

ID of the address/geofence

Responses

Response samples

Content type
application/json
{
  • "contacts": [
    ],
  • "createdAtTime": "2019-05-18T20:27:35Z",
  • "formattedAddress": "350 Rhode Island St, San Francisco, CA",
  • "geofence": {
    },
  • "id": 123,
  • "name": "Samsara HQ",
  • "notes": "Delivery site 1",
  • "tags": [
    ]
}

/addresses/{addressId}

Delete an address.

path Parameters
addressId
required
integer <int64>

ID of the address/geofence

Responses

Response samples

Content type
application/json
"string"

/addresses/{addressId}

Update the name, formatted address, geofence, notes, or tag and contact Ids for an address. The set of tags or contacts associated with this address will be updated to exactly match the list of IDs passed in. To remove all tags or contacts from an address, pass an empty list; to remove notes, pass an empty string.

path Parameters
addressId
required
integer <int64>

ID of the address/geofence

Request Body schema: application/json

Update parts of an address's value. If the geofence 'circle' or 'polygon' key is specified, the update will change the type of geofence accordingly.

contactIds
Array of numbers <int64> (ContactIds) [ items <int64 > ]

A list of IDs for contact book entries.

formattedAddress
string

The full address associated with this address/geofence, as it might be recognized by maps.google.com

object (AddressGeofence)

The geofence that defines this address and its bounds. This can either be a circle, or a polygon - only one key should be provided, depending on the geofence type.

name
string

The name of this address/geofence

notes
string (AddressNotes)

Notes associated with an address.

tagIds
Array of numbers <int64> (TagIds) [ items <int64 > ]

A list of tag IDs.

Responses

Request samples

Content type
application/json
{
  • "contactIds": [
    ],
  • "formattedAddress": "350 Rhode Island St, San Francisco, CA",
  • "geofence": {
    },
  • "name": "Samsara HQ",
  • "notes": "Delivery site 1",
  • "tagIds": [
    ]
}

Response samples

Content type
application/json
"string"

/fleet/add_address

This method adds an address book entry.

Request Body schema: application/json
address
required
string

The address of the entry to add, as it would be recognized if provided to maps.google.com.

name
required
string

Name of the location to add to the address book.

radius
required
integer

Radius in meters of the address (used for matching vehicle trip stops to this location).

Responses

Request samples

Content type
application/json
{
  • "address": "501 York St",
  • "name": "HQ",
  • "radius": 10
}

Response samples

Content type
application/json
"string"

/fleet/assets

Fetch all of the assets.

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ]
}

/fleet/assets/locations

Fetch current locations of all assets.

query Parameters
startingAfter
string

Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'endingBefore' parameter.

endingBefore
string

Pagination parameter indicating the cursor position to return results before. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'startingAfter' parameter.

limit
number <int64>

Pagination parameter indicating the number of results to return in this request. Used in conjunction with either 'startingAfter' or 'endingBefore'.

tagIds
Array of strings

A comma-separated list of tag IDs. Example: tagIds=1000,1001

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "pagination": {
    }
}

/fleet/assets/reefers

Fetches all reefers and reefer-specific stats.

query Parameters
startMs
required
integer <int64>

Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs.

endMs
required
integer <int64>

Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs.

startingAfter
string

Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'endingBefore' parameter.

endingBefore
string

Pagination parameter indicating the cursor position to return results before. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'startingAfter' parameter.

limit
number <int64>

Pagination parameter indicating the number of results to return in this request. Used in conjunction with either 'startingAfter' or 'endingBefore'.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

/fleet/assets/{assetId}/locations

Fetch the historical locations for the asset.

path Parameters
asset_id
required
integer <int64>

ID of the asset. Must contain only digits 0-9.

query Parameters
startMs
required
integer <int64>

Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs.

endMs
required
integer <int64>

Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/assets/{assetId}/reefer

Fetch the reefer-specific stats of an asset.

path Parameters
asset_id
required
integer <int64>

ID of the asset. Must contain only digits 0-9.

query Parameters
startMs
required
integer <int64>

Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs.

endMs
required
integer <int64>

Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs.

Responses

Response samples

Content type
application/json
{
  • "assetType": "Thermo King",
  • "id": 1,
  • "name": "Reefer 123",
  • "reeferStats": {
    }
}

/fleet/dispatch/routes

List all routes scheduled within a given time period. Routes are returned if both of the following conditions are met:

  • The route's scheduled_start_ms is before the timestamp: end_time (defaults to now)
  • The route's scheduled_end_ms is after the timestamp: end_time - duration (defaults to now - 24 hours)

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.

query Parameters
end_time
integer <int64>

Time in unix milliseconds that represents the end time of the requested time interval. See above for a description of how routes are returned. Defaults to now.

duration
integer <int64>

Time in milliseconds that represents the duration before end_time to query. Defaults to 24 hours.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/dispatch/routes

Create a new dispatch route.

Request Body schema: application/json
required
Array of objects (DispatchJobCreate)

The dispatch jobs to create for this route.

complete_last_stop_on_arrival
boolean
Default: true

When set to true (default), this causes the Route to complete on arrival at the final stop. When set to false, the last stop will capture arrival and departure separately as with other stops.

driver_id
integer <int64>

ID of the driver assigned to the dispatch route. Note that driver_id and vehicle_id are mutually exclusive. If neither is specified, then the route is unassigned.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

name
required
string

Descriptive name of this route.

notes
string

Notes regarding the details of this route; maximum of 2000 characters; newline characters ('\n')can be used for formatting.

scheduled_end_ms
integer <int64>

The time in Unix epoch milliseconds that the last job in the route is scheduled to end.

scheduled_meters
integer <int64>

The distance expected to be traveled for this route in meters.

scheduled_start_ms
required
integer <int64>

The time in Unix epoch milliseconds that the route is scheduled to start.

start_location_address
string

The address of the route's starting location, as it would be recognized if provided to maps.google.com. Optional if a valid start location address ID is provided.

start_location_address_id
integer <int64>

ID of the start location associated with an address book entry. Optional if valid values are provided for start location address and latitude/longitude. If a valid start location address ID is provided, address/latitude/longitude will be used from the address book entry. Name of the address book entry will only be used if the start location name is not provided.

start_location_lat
number <double>

Latitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_lng
number <double>

Longitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_name
string

The name of the route's starting location. If provided, it will take precedence over the name of the address book entry.

trailer_id
integer <int64>

ID of the trailer assigned to the dispatch route. Note that trailers can only be assigned to routes that have a Vehicle or Driver assigned to them.

vehicle_id
integer <int64>

ID of the vehicle assigned to the dispatch route. Note that vehicle_id and driver_id are mutually exclusive. If neither is specified, then the route is unassigned.

Responses

Request samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

Response samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": 556,
  • "actual_end_ms": 1462882101000,
  • "actual_start_ms": 1462882098000,
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "group_id": 101,
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "odometer_end_meters": 2000000,
  • "odometer_start_meters": 1000000,
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

/fleet/dispatch/routes/job_updates

Fetch all updates to a job including route data in the last 24 hours or subsequent to an sequence ID. Returns a maximum of 500 job updates. If more than 500 job updates are available, another request made with the prior request's sequence_id will return the next set of available job updates.

query Parameters
sequence_id
string

Sequence ID from the response payload of the last request. Defaults to fetching updates from last 24 hours.

include
string

Optionally set include=route to include route object in response payload.

Responses

Response samples

Content type
application/json
{
  • "job_updates": [
    ],
  • "sequence_id": "eyJpZCI6MywiY3JlYXRlZF9hdCI6MTQ5OTQyOTIyMDAwMn0="
}

/fleet/dispatch/routes/{route_id}

Fetch a dispatch route by id.

path Parameters
route_id_or_external_id
required
string

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

Responses

Response samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": 556,
  • "actual_end_ms": 1462882101000,
  • "actual_start_ms": 1462882098000,
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "group_id": 101,
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "odometer_end_meters": 2000000,
  • "odometer_start_meters": 1000000,
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

/fleet/dispatch/routes/{route_id}/

Update the dispatch route. Examples of this include:

  • Adding, removing, and/or editing jobs in the dispatch_jobs array. If you add a job to this array, you do not need to include an id field. One will be created automatically for that new job.
  • Updating the assigned driver or vehicle. (Routes may be assigned to a driver or a vehicle, but not both).
  • Updating the location and/or timing information of the route.
path Parameters
route_id_or_external_id
required
string

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 schema: application/json
required
Array of objects (DispatchJobUpdate)

The dispatch jobs for the route.

id
required
integer <int64>

ID of route. This must match the route ID passed in URL.

complete_last_stop_on_arrival
boolean
Default: true

When set to true (default), this causes the Route to complete on arrival at the final stop. When set to false, the last stop will capture arrival and departure separately as with other stops.

driver_id
integer <int64>

ID of the driver assigned to the dispatch route. Note that driver_id and vehicle_id are mutually exclusive. If neither is specified, then the route is unassigned.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

name
required
string

Descriptive name of this route.

notes
string

Notes regarding the details of this route; maximum of 2000 characters; newline characters ('\n')can be used for formatting.

scheduled_end_ms
integer <int64>

The time in Unix epoch milliseconds that the last job in the route is scheduled to end.

scheduled_meters
integer <int64>

The distance expected to be traveled for this route in meters.

scheduled_start_ms
required
integer <int64>

The time in Unix epoch milliseconds that the route is scheduled to start.

start_location_address
string

The address of the route's starting location, as it would be recognized if provided to maps.google.com. Optional if a valid start location address ID is provided.

start_location_address_id
integer <int64>

ID of the start location associated with an address book entry. Optional if valid values are provided for start location address and latitude/longitude. If a valid start location address ID is provided, address/latitude/longitude will be used from the address book entry. Name of the address book entry will only be used if the start location name is not provided.

start_location_lat
number <double>

Latitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_lng
number <double>

Longitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_name
string

The name of the route's starting location. If provided, it will take precedence over the name of the address book entry.

trailer_id
integer <int64>

ID of the trailer assigned to the dispatch route. Note that trailers can only be assigned to routes that have a Vehicle or Driver assigned to them.

vehicle_id
integer <int64>

ID of the vehicle assigned to the dispatch route. Note that vehicle_id and driver_id are mutually exclusive. If neither is specified, then the route is unassigned.

Responses

Request samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": "42",
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

Response samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": 556,
  • "actual_end_ms": 1462882101000,
  • "actual_start_ms": 1462882098000,
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "group_id": 101,
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "odometer_end_meters": 2000000,
  • "odometer_start_meters": 1000000,
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

/fleet/dispatch/routes/{route_id}/

Delete a dispatch route and its associated jobs.

path Parameters
route_id_or_external_id
required
string

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 schema: application/json
apply_to_future_routes
boolean

This is only for a recurring route. If set to true, delete all following runs of the route. If set to false, only delete the current route.

Responses

Request samples

Content type
application/json
{
  • "apply_to_future_routes": true
}

Response samples

Content type
application/json
"string"

/fleet/dispatch/routes/{route_id}/history

Fetch the history of a dispatch route.

path Parameters
route_id_or_external_id
required
string

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

query Parameters
start_time
integer <int64>

Timestamp representing the start of the period to fetch, inclusive. Used in combination with end_time. Defaults to 0.

end_time
integer <int64>

Timestamp representing the end of the period to fetch, inclusive. Used in combination with start_time. Defaults to nowMs.

Responses

Response samples

Content type
application/json
{
  • "history": [
    ]
}

/fleet/drivers

Get all active drivers. When drivers leave an organization, you can deactivate them. Use DELETE /v1/fleet/drivers/{id} to deactivate drivers and GET /v1/fleet/drivers/inactive to get inactive drivers. Inactive driver records will still be part of reports such as Hours of Service.

Responses

Response samples

Content type
application/json
{
  • "drivers": [
    ]
}

/fleet/drivers/create

Create a new driver.

Request Body schema: application/json

Driver creation body

password
required
string

Driver's password for the driver app.

tagIds
Array of numbers <int64> (TagIds) [ items <int64 > ]

A list of tag IDs.

eldAdverseWeatherExemptionEnabled
boolean

Flag indicating this driver may use Adverse Weather exemptions in ELD logs.

eldBigDayExemptionEnabled
boolean

Flag indicating this driver may use Big Day excemptions in ELD logs.

eldDayStartHour
integer

0 indicating midnight-to-midnight ELD driving hours, 12 to indicate noon-to-noon driving hours.

eldExempt
boolean

Flag indicating this driver is exempt from the Electronic Logging Mandate.

eldExemptReason
string

Reason that this driver is exempt from the Electronic Logging Mandate (see eldExempt).

eldPcEnabled
boolean
Default: false

Flag indicating this driver may select the Personal Conveyance duty status in ELD logs.

eldYmEnabled
boolean
Default: false

Flag indicating this driver may select the Yard Move duty status in ELD logs.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

groupId
integer <int64>

Deprecated.

licenseNumber
string

Driver's state issued license number.

licenseState
string

Abbreviation of state that issued driver's license.

name
required
string

Driver's name.

notes
string

Notes about the driver.

phone
string

Driver's phone number. Please include only digits, ex. 4157771234

timezone
string

Home terminal timezone, in order to indicate what time zone should be used to calculate the ELD logs. Driver timezones use IANA timezone database keys (e.g. America/Los_Angeles, America/New_York, Europe/London, etc.). You can find a mapping of common timezone formats to IANA timezone keys here.

username
string

Driver's login username into the driver app. The username may not contain spaces or @.

vehicleGroupTagId
integer <int64>

ID of the tag which determines which vehicles a driver will see when selecting vehicles

vehicleId
integer <int64>

ID of the vehicle assigned to the driver for static vehicle assignments. (uncommon).

Responses

Request samples

Content type
application/json
{
  • "password": "mypassword",
  • "tagIds": [
    ],
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

Response samples

Content type
application/json
{
  • "id": 556,
  • "isDeactivated": true,
  • "tags": [
    ],
  • "currentVehicleId": 879,
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

/fleet/drivers/document_types

Fetch all of the document types.

Responses

Response samples

Content type
application/json
{
  • "conditionalFieldSections": [
    ],
  • "fieldTypes": [
    ],
  • "name": "Damage Report",
  • "orgId": 123,
  • "uuid": "4aff772c-a7bb-45e6-8e41-6a53e34feb83"
}

/fleet/drivers/documents

Fetch all of the documents.

query Parameters
endMs
integer <int64>

Time in unix milliseconds that represents the oldest documents to return. Used in combination with durationMs. Defaults to now.

durationMs
integer <int64>

Time in milliseconds that represents the duration before endMs to query. Defaults to 24 hours.

queryBy
string <string>
Enum: "created" "updated"

Retrieve most recent documents based on either driverCreatedAtMs or serverUpdatedAtMs. If no value is provided, the default is driverCreatedAtMs.

Responses

Response samples

Content type
application/json
{
  • "driverDocuments": [
    ]
}

/fleet/drivers/inactive

Get all inactive drivers. When drivers leave an organization, you can deactivate them. You can use DELETE /v1/fleet/drivers/{id} to deactivate drivers. Inactive driver records will still be part of reports such as Hours of Service.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/drivers/inactive/{driver_id or external_id}

Get an inactive driver. When drivers leave an organization, you can deactivate them. You can use DELETE /v1/fleet/drivers/{id} to deactivate drivers. You can use PUT /v1/fleet/drivers/{id} to reactivate drivers. Inactive driver records will still be part of reports such as Hours of Service.

path Parameters
driver_id_or_external_id
required
string

ID of the driver. 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

Responses

Response samples

Content type
application/json
{
  • "id": 556,
  • "isDeactivated": true,
  • "tags": [
    ],
  • "currentVehicleId": 879,
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

/fleet/drivers/inactive/{driver_id or external_id}

Reactivate a driver.

path Parameters
driver_id_or_external_id
required
string

ID of the driver. 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 schema: application/json

Driver reactivation body

reactivate
required
boolean

True indicates that this driver should be reactivated.

Responses

Request samples

Content type
application/json
{
  • "reactivate": true
}

Response samples

Content type
application/json
{
  • "id": 556,
  • "isDeactivated": true,
  • "tags": [
    ],
  • "currentVehicleId": 879,
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

/fleet/drivers/summary

Get the distance and time each driver in an organization has driven in a given time period.

Note: If data is still being uploaded from the Samsara Driver App, it may not be completely reflected in the response from this endpoint. The best practice is to wait a couple of days before querying this endpoint to make sure that all data from the Samsara Driver App has been uploaded.

query Parameters
snap_to_day_bounds
boolean

Snap query result to HOS day boundaries.

Request Body schema: application/json
endMs
required
integer <int64>

End time (ms) of queried time period. Must be greater than startMs.

orgId
required
integer <int64>

Organization ID that the drivers belong to

startMs
required
integer <int64>

Start time (ms) of queried time period.

Responses

Request samples

Content type
application/json
{
  • "endMs": 1462881998034,
  • "orgId": 555,
  • "startMs": 1462878398034
}

Response samples

Content type
application/json
{
  • "Summaries": [
    ]
}

/fleet/drivers/{driverId}/safety/score

Fetch the safety score for the driver.

path Parameters
driverId
required
integer <int64>

ID of the driver. Must contain only digits 0-9.

query Parameters
startMs
required
integer <int64>

Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs. Total duration (endMs - startMs) must be greater than or equal to 1 hour.

endMs
required
integer <int64>

Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs. Total duration (endMs - startMs) must be greater than or equal to 1 hour.

Responses

Response samples

Content type
application/json
{
  • "crashCount": 0,
  • "driverId": 1234,
  • "harshAccelCount": 1,
  • "harshBrakingCount": 2,
  • "harshEvents": [
    ],
  • "harshTurningCount": 0,
  • "safetyScore": 97,
  • "safetyScoreRank": "26",
  • "timeOverSpeedLimitMs": 3769,
  • "totalDistanceDrivenMeters": 291836,
  • "totalHarshEventCount": 3,
  • "totalTimeDrivenMs": 19708293
}

/fleet/drivers/{driver_id or external_id}

Get an active driver. When drivers leave an organization, you can deactivate them. Use GET /v1/fleet/drivers/inactive/{id} to get an inactive driver, and use DELETE /v1/fleet/drivers/{id} to deactivate drivers.

path Parameters
driver_id_or_external_id
required
string

ID of the driver. 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

Responses

Response samples

Content type
application/json
{
  • "id": 556,
  • "isDeactivated": true,
  • "tags": [
    ],
  • "currentVehicleId": 879,
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

/fleet/drivers/{driver_id or external_id}

Deactivate a driver. You can use PUT /v1/fleet/drivers/{id} to reactivate a driver.

path Parameters
driver_id_or_external_id
required
string

ID of the driver. 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

Responses

Response samples

Content type
application/json
"string"

/fleet/drivers/{driver_id or external_id}

Update a driver. You can update both active and inactive drivers. Active drivers are drivers that are currently part of your fleet. Inactive drivers are drivers that are not currently part of your fleet. Inactive driver historical data will still be available via different reports such as Hours of Service. Use DELETE /v1/fleet/drivers/{id} to deactivate drivers, and PUT /v1/fleet/drivers/{id} to reactivate drivers.

path Parameters
driver_id_or_external_id
required
string

ID of the driver. 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 schema: application/json

Driver update body

tagIds
Array of numbers <int64> (TagIds) [ items <int64 > ]

A list of tag IDs.

eldAdverseWeatherExemptionEnabled
boolean

Flag indicating this driver may use Adverse Weather exemptions in ELD logs.

eldBigDayExemptionEnabled
boolean

Flag indicating this driver may use Big Day excemptions in ELD logs.

eldDayStartHour
integer

0 indicating midnight-to-midnight ELD driving hours, 12 to indicate noon-to-noon driving hours.

eldExempt
boolean

Flag indicating this driver is exempt from the Electronic Logging Mandate.

eldExemptReason
string

Reason that this driver is exempt from the Electronic Logging Mandate (see eldExempt).

eldPcEnabled
boolean
Default: false

Flag indicating this driver may select the Personal Conveyance duty status in ELD logs.

eldYmEnabled
boolean
Default: false

Flag indicating this driver may select the Yard Move duty status in ELD logs.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

groupId
integer <int64>

Deprecated.

licenseNumber
string

Driver's state issued license number.

licenseState
string

Abbreviation of state that issued driver's license.

name
required
string

Driver's name.

notes
string

Notes about the driver.

phone
string

Driver's phone number. Please include only digits, ex. 4157771234

timezone
string

Home terminal timezone, in order to indicate what time zone should be used to calculate the ELD logs. Driver timezones use IANA timezone database keys (e.g. America/Los_Angeles, America/New_York, Europe/London, etc.). You can find a mapping of common timezone formats to IANA timezone keys here.

username
string

Driver's login username into the driver app. The username may not contain spaces or @.

vehicleGroupTagId
integer <int64>

ID of the tag which determines which vehicles a driver will see when selecting vehicles

vehicleId
integer <int64>

ID of the vehicle assigned to the driver for static vehicle assignments. (uncommon).

Responses

Request samples

Content type
application/json
{
  • "tagIds": [
    ],
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

Response samples

Content type
application/json
{
  • "id": 556,
  • "isDeactivated": true,
  • "tags": [
    ],
  • "currentVehicleId": 879,
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

/fleet/drivers/{driver_id}/dispatch/routes

List all routes scheduled within a given time period for the given driver. Routes are returned if both of the following conditions are met:

  • The route's scheduled_start_ms is before the timestamp: end_time (defaults to now)
  • The route's scheduled_end_ms is after the timestamp: end_time - duration (defaults to now - 24 hours)

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.

path Parameters
driver_id
required
integer <int64>

ID of the driver with the associated routes. Must contain only digits 0-9.

query Parameters
end_time
integer <int64>

Time in unix milliseconds that represents the end time of the requested time interval. See above for a description of how routes are returned. Defaults to now.

duration
integer <int64>

Time in milliseconds that represents the duration before end_time to query. Defaults to 24 hours.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/drivers/{driver_id}/dispatch/routes

Create a new dispatch route for the driver with driver_id.

path Parameters
driver_id
required
integer <int64>

ID of the driver with the associated routes. Must contain only digits 0-9.

Request Body schema: application/json
required
Array of objects (DispatchJobCreate)

The dispatch jobs to create for this route.

complete_last_stop_on_arrival
boolean
Default: true

When set to true (default), this causes the Route to complete on arrival at the final stop. When set to false, the last stop will capture arrival and departure separately as with other stops.

driver_id
integer <int64>

ID of the driver assigned to the dispatch route. Note that driver_id and vehicle_id are mutually exclusive. If neither is specified, then the route is unassigned.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

name
required
string

Descriptive name of this route.

notes
string

Notes regarding the details of this route; maximum of 2000 characters; newline characters ('\n')can be used for formatting.

scheduled_end_ms
integer <int64>

The time in Unix epoch milliseconds that the last job in the route is scheduled to end.

scheduled_meters
integer <int64>

The distance expected to be traveled for this route in meters.

scheduled_start_ms
required
integer <int64>

The time in Unix epoch milliseconds that the route is scheduled to start.

start_location_address
string

The address of the route's starting location, as it would be recognized if provided to maps.google.com. Optional if a valid start location address ID is provided.

start_location_address_id
integer <int64>

ID of the start location associated with an address book entry. Optional if valid values are provided for start location address and latitude/longitude. If a valid start location address ID is provided, address/latitude/longitude will be used from the address book entry. Name of the address book entry will only be used if the start location name is not provided.

start_location_lat
number <double>

Latitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_lng
number <double>

Longitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_name
string

The name of the route's starting location. If provided, it will take precedence over the name of the address book entry.

trailer_id
integer <int64>

ID of the trailer assigned to the dispatch route. Note that trailers can only be assigned to routes that have a Vehicle or Driver assigned to them.

vehicle_id
integer <int64>

ID of the vehicle assigned to the dispatch route. Note that vehicle_id and driver_id are mutually exclusive. If neither is specified, then the route is unassigned.

Responses

Request samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

Response samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": 556,
  • "actual_end_ms": 1462882101000,
  • "actual_start_ms": 1462882098000,
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "group_id": 101,
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "odometer_end_meters": 2000000,
  • "odometer_start_meters": 1000000,
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

/fleet/drivers/{driver_id}/documents

Create a driver document for the given driver.

You can create a document in one of two states: "Required" or "Submitted":

  • Setting the document state to "Submitted" will submit the document on behalf of the driver.

  • Setting the document state to "Required" will create a pre-populated document for the driver to fill out in the Driver App.

Populating document fields

You populate a document's fields according to the document's document type. You can retrieve document types using the GET /v1/fleet/drivers/document_types endpoint.

You must populate a document's fields using the field labels and value types, and the fields must be listed in the same order they appear in the document type. See the request schema below for more details.

Setting document fields to default values

If a document's state is set to "Required", you can set document fields to default values by omitting the field value from the request body or explicitly setting it to null. For example:


{

  "documentTypeUuid": "79008acc-56d6-49f4-b5d2-4101ce4b497c",

  "fields": [

    {

      "label": "Number Field",

      "valueType": "ValueType_Number",

      "numberValue": null

    },

    {

      "label": "Signature Field",

      "valueType": "ValueType_Signature"

    }

  ],

  "dispatchJobId": 4333299083,

  "state":"Required"

}

In the request above, the value for the number field is explicitly set to null, and the value for the signature field is omitted. Both forms are accepted and functionally equivalent. Both will result in the field being pre-populated with a default value.

path Parameters
driver_id
required
integer <int64>

ID of the driver for whom the document is created. Must contain only digits 0-9.

Request Body schema: application/json

To create a document for a given document type, provide the documentTypeUuid of the type of document you'd like to create. Then, pass in the fields of the document in the same order that they show up in the given document type.

documentTypeUuid
required
string

Universally unique identifier for the document type that this document is being created for.

required
Array of objects (DocumentCreateFields)

List of fields for the document. The fields must be listed in the order that that they appear in the document type. Values of fields can be set to null or omitted if the document state is set to "Required".

dispatchJobId
integer <int64>

ID of the Samsara dispatch job for which the document is submitted.

name
string [ 1 .. 255 ] characters

Custom name of the document. If no custom name is given to the document, the admin dashboard and driver app will display the template name as the default document name.

notes
string

Notes submitted with this document.

state
string
Default: "Required"
Enum: "Required" "Submitted"

The condition of the document created for the driver. Can be either Required or Submitted. If no value is specified, state defaults to Required. Required documents are pre-populated documents for the Driver to fill out in the Driver App and have not yet been submitted. Submitted documents will show up as submitted by the driver through the driver app.

Responses

Request samples

Content type
application/json
{
  • "documentTypeUuid": "4aff772c-a7bb-45e6-8e41-6a53e34feb83",
  • "fields": [
    ],
  • "dispatchJobId": 773,
  • "name": "Fuel Receipt Wichita",
  • "notes": "Fueled up before delivery.",
  • "state": "Required"
}

Response samples

Content type
application/json
{
  • "documentType": "Fuel Receipt",
  • "driverCreatedAtMs": 1462881998034,
  • "driverId": 555,
  • "fields": [
    ],
  • "id": "2018_42424242",
  • "orgId": 555,
  • "serverCreatedAtMs": 1462881998034,
  • "serverUpdatedAtMs": 1462881998034,
  • "vehicleId": 222,
  • "dispatchJobId": 773,
  • "name": "Fuel Receipt Wichita",
  • "notes": "Fueled up before delivery.",
  • "state": "Submitted"
}

/fleet/drivers/{driver_id}/documents/{document_id}

Fetches a single document submission by driver.

path Parameters
driver_id
required
integer <int64>

ID of the driver who submitted the document. Must contain only digits 0-9.

document_id
required
string

ID of document.

Responses

Response samples

Content type
application/json
{
  • "documentType": "Fuel Receipt",
  • "driverCreatedAtMs": 1462881998034,
  • "driverId": 555,
  • "fields": [
    ],
  • "id": "2018_42424242",
  • "orgId": 555,
  • "serverCreatedAtMs": 1462881998034,
  • "serverUpdatedAtMs": 1462881998034,
  • "vehicleId": 222,
  • "dispatchJobId": 773,
  • "name": "Fuel Receipt Wichita",
  • "notes": "Fueled up before delivery.",
  • "state": "Submitted"
}

/fleet/drivers/{driver_id}/documents/{document_id}

Deletes a single document submission by driver.

path Parameters
driver_id
required
integer <int64>

ID of the driver who submitted the document. Must contain only digits 0-9.

document_id
required
string

ID of document.

Responses

Response samples

Content type
application/json
"string"

Set a duty status for a specific driver

Set an individual driver’s current duty status to 'On Duty' or 'Off Duty'.

To ensure compliance with the ELD Mandate, only authenticated drivers can make direct duty status changes on their own logbook. Any system external to the Samsara Driver App using this endpoint to trigger duty status changes must ensure that such changes are only triggered directly by the driver in question and that the driver has been properly authenticated. This endpoint should not be used to algorithmically trigger duty status changes nor should it be used by personnel besides the driver to trigger duty status changes on the driver’s behalf. Carriers and their drivers are ultimately responsible for maintaining accurate logs and should confirm that their use of the endpoint is compliant with the ELD Mandate.

path Parameters
driver_id
required
integer <int64>

ID of the driver for whom the duty status is being set.

Request Body schema: application/json
duty_status
required
string

Duty status to set the driver to. The only supported values are 'ON_DUTY' and 'OFF_DUTY'.

location
string

Location to associate the duty status change with.

remarks
string

Remark to associate the duty status change with.

status_change_at_ms
number <int64>

Timestamp that the duty status will begin at specified in milliseconds UNIX time. Defaults to the current time if left blank. This can only be set to up to 8 hours in the past.

vehicle_id
number <int64>

Vehicle ID to associate the duty status change with.

Responses

Request samples

Content type
application/json
{
  • "duty_status": "ON_DUTY",
  • "location": "Loading dock",
  • "remarks": "Beginning On Duty Shift",
  • "status_change_at_ms": 1580834793568,
  • "vehicle_id": 1234
}

Response samples

Content type
application/json
"string"

/fleet/drivers/{driver_id}/hos_daily_logs

Get summarized daily Hours of Service charts for a specified driver.

The response will contain a list of days, where each entry in the list is the driver's summarized hours of service for that entire day.

The time range for a "day" is defined by the driver's eldDayStartHour. By default, this is 0, which indicates the driver's "day" is from midnight to midnight in the driver's respective timezone. This value is configurable per driver.

The startMs and endMs parameters indicate start and end for the date range you'd like to query. These parameters are inclusive. This means that the response will include the "day" that contains startMs and the "day" that contains endMs. For example:

Let's say a driver's eldDayStartHour is 0 and their timezone is America/Chicago.

If startMs was 1576080000000 (December 11, 2019 10:00:00 AM America/Chicago) and an endMs was 1576166400000 (December 12, 2019 10:00:00 AM America/Los_Angeles), then the response will contain a two day entries: [December 11, 2019 12:00:00 AM America/Chicago to December 12, 2019 12:00:00 AM America/Chicago], and [December 12, 2019 12:00:00 AM America/Chicago to December 13, 2019 12:00:00 AM America/Chicago].

Note: If data is still being uploaded from the Samsara Driver App, it may not be completely reflected in the response from this endpoint. The best practice is to wait a couple of days before querying this endpoint to make sure that all data from the Samsara Driver App has been uploaded.

path Parameters
driver_id
required
integer <int64>

ID of the driver with HOS logs.

query Parameters
startMs
required
integer <int64>

Beginning of the time range, specified in milliseconds UNIX time.

endMs
required
integer <int64>

End of the time range, specified in milliseconds UNIX time. Note: This timestamp should not be in the future. Providing a timestamp in the future will result in unpredictable behavior from the API. (I.e. this field should always be less than or equal to the current time).

Responses

Response samples

Content type
application/json
{
  • "days": [
    ]
}

/fleet/hos_authentication_logs

Get the HOS (hours of service) signin and signout logs for the specified driver. The response includes 4 fields that are now deprecated.

Note: If data is still being uploaded from the Samsara Driver App, it may not be completely reflected in the response from this endpoint. The best practice is to wait a couple of days before querying this endpoint to make sure that all data from the Samsara Driver App has been uploaded.

query Parameters
driverId
required
integer <int64>

Driver ID to query.

startMs
required
integer <int64>

Beginning of the time range, specified in milliseconds UNIX time.

endMs
required
integer <int64>

End of the time range, specified in milliseconds UNIX time.

Responses

Response samples

Content type
application/json
{
  • "authenticationLogs": [
    ]
}

/fleet/hos_logs

Get the HOS (hours of service) logs for the specified driver. This method returns all the HOS statuses that the driver was in during this time period.

Note: If data is still being uploaded from the Samsara Driver App, it may not be completely reflected in the response from this endpoint. The best practice is to wait a couple of days before querying this endpoint to make sure that all data from the Samsara Driver App has been uploaded.

Request Body schema: application/json
driverId
required
integer <int64>

Driver ID to query.

endMs
required
integer

End of the time range, specified in milliseconds UNIX time.

startMs
required
integer

Beginning of the time range, specified in milliseconds UNIX time.

Responses

Request samples

Content type
application/json
{
  • "driverId": 444,
  • "endMs": 1462881998034,
  • "startMs": 1462878398034
}

Response samples

Content type
application/json
{
  • "logs": [
    ]
}

/fleet/hos_logs_summary

Get the current HOS status for all drivers. Note that this includes inactive as well as active drivers. You may need to upgrade your API token to version 2019-07-31 or later to leverage response pagination. See here.

Note: If data is still being uploaded from the Samsara Driver App, it may not be completely reflected in the response from this endpoint. The best practice is to wait a couple of days before querying this endpoint to make sure that all data from the Samsara Driver App has been uploaded.

query Parameters
after
string

Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter.

limit
number <int64>

Pagination parameter indicating the number of results to return in this request. Used in conjunction with 'after'.

Responses

Response samples

Content type
application/json
{
  • "drivers": [
    ],
  • "pagination": {
    }
}

/fleet/list

Get list of the vehicles. This method returns a list of the vehicles in the Samsara Cloud and information about them.

query Parameters
startingAfter
string

Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'endingBefore' parameter.

endingBefore
string

Pagination parameter indicating the cursor position to return results before. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'startingAfter' parameter.

limit
number <int64>

Pagination parameter indicating the number of results to return in this request. Used in conjunction with either 'startingAfter' or 'endingBefore'.

Responses

Response samples

Content type
application/json
{
  • "groupId": 101,
  • "pagination": {
    },
  • "vehicles": [
    ]
}

/fleet/locations

Get current location of vehicles.

query Parameters
after
string

Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter.

limit
number <int64> [ 1 .. 512 ]
Default: 512

Pagination parameter indicating the number of results to return in this request. Used in conjunction with 'after'.

vehicleIds
Array of strings

A comma-separated list of vehicle IDs. Example: vehicleIds=1000,1001

tagIds
Array of strings

A comma-separated list of tag IDs. Example: tagIds=1000,1001

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "vehicles": [
    ]
}

/fleet/maintenance/dvirs

Get DVIRs for the org within provided time constraints

query Parameters
end_ms
required
integer

Time in millis until the last dvir log.

duration_ms
required
integer <= 7776000000

Time in millis which corresponds to the duration before the end_ms. Must be less than or equal to 90 days.

Responses

Response samples

Content type
application/json
{
  • "dvirs": [
    ]
}

/fleet/maintenance/dvirs

Create a new dvir, marking a vehicle or trailer safe or unsafe.

Request Body schema: application/json

DVIR creation body

inspectionType
required
string
Value: "mechanic"

Only type 'mechanic' is currently accepted.

mechanicNotes
string

Any notes from the mechanic.

odometerMiles
integer

The current odometer of the vehicle.

previousDefectsCorrected
boolean

Whether any previous defects were corrected. If this vehicle or trailer was previously marked unsafe, and this DVIR marks it as safe, either previousDefectsCorrected or previousDefectsIgnored must be true.

previousDefectsIgnored
boolean

Whether any previous defects were ignored. If this vehicle or trailer was previously marked unsafe, and this DVIR marks it as safe, either previousDefectsCorrected or previousDefectsIgnored must be true.

resolvedDefectIds
Array of integers <int64> [ items <int64 > ]

List of defect IDs to resolve. The defects must be associated with the provided vehicle or trailer.

safe
required
string
Enum: "safe" "unsafe"

Whether or not this vehicle or trailer is safe to drive.

trailerId
integer

Id of trailer being inspected. Either vehicleId or trailerId must be provided.

userEmail
required
string

The Samsara login email for the person creating the DVIR. The email must correspond to a Samsara user's email.

vehicleId
integer

Id of vehicle being inspected. Either vehicleId or trailerId must be provided.

Responses

Request samples

Content type
application/json
{
  • "inspectionType": "mechanic",
  • "mechanicNotes": "Replaced headlight on passenger side.",
  • "odometerMiles": 38426,
  • "previousDefectsCorrected": true,
  • "previousDefectsIgnored": false,
  • "resolvedDefectIds": [
    ],
  • "safe": "safe",
  • "trailerId": 11,
  • "userEmail": "j.smith@yahoo.com",
  • "vehicleId": 10
}

Response samples

Content type
application/json
{
  • "authorSignature": {
    },
  • "defectsCorrected": true,
  • "defectsNeedNotBeCorrected": false,
  • "id": 19,
  • "inspectionType": "pre trip",
  • "mechanicNotes": "The vehicle is now safe.",
  • "mechanicOrAgentSignature": {
    },
  • "nextDriverSignature": {
    },
  • "odometerMiles": 49912,
  • "startedAtMs": 1453449599999,
  • "timeMs": 1453449599999,
  • "trailerDefects": [
    ],
  • "trailerId": 19,
  • "trailerName": "Storer's Trailer 19",
  • "vehicle": {
    },
  • "vehicleCondition": "SATISFACTORY",
  • "vehicleDefects": [
    ]
}

/fleet/maintenance/list

Get list of the vehicles with any engine faults or check light data.

We suggest you use our updated and more flexible vehicle/stats endpoints for fetching vehicle fault codes.

Responses

Response samples

Content type
application/json
{
  • "vehicles": [
    ]
}

/fleet/set_data

This API allows you to update metadata for a single vehicle.

Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "vehicles": [
    ]
}

Response samples

Content type
application/json
"string"

/fleet/trailers/assignments

Fetch trailer assignment data for all trailers in your organization.

query Parameters
startMs
integer <int64>

Timestamp in Unix epoch miliseconds representing the start of the period to fetch. Omitting both startMs and endMs only returns current assignments.

endMs
integer <int64>

Timestamp in Unix epoch miliseconds representing the end of the period to fetch. Omitting endMs sets endMs as the current time

limit
number <int64>

Pagination parameter indicating the number of results to return in this request. Used in conjunction with either 'startingAfter' or 'endingBefore'.

startingAfter
string

Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'endingBefore' parameter.

endingBefore
string

Pagination parameter indicating the cursor position to return results before. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'startingAfter' parameter.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "trailers": [
    ]
}

/fleet/trailers/{trailerId}/assignments

Fetch trailer assignment data for a single trailer.

path Parameters
trailerId
required
integer <int64>

ID of trailer. Must contain only digits 0-9.

query Parameters
startMs
integer <int64>

Timestamp in Unix epoch milliseconds representing the start of the period to fetch. Omitting both startMs and endMs only returns current assignments.

endMs
integer <int64>

Timestamp in Unix epoch milliseconds representing the end of the period to fetch. Omitting endMs sets endMs as the current time

Responses

Response samples

Content type
application/json
{
  • "id": 2041,
  • "name": "myTrailer",
  • "trailerAssignments": [
    ]
}

/fleet/trips

Get historical trips data for specified vehicle. This method returns a set of historical trips data for the specified vehicle in the specified time range.

query Parameters
vehicleId
required
integer <int64>

Vehicle ID to query.

startMs
required
integer

Beginning of the time range, specified in milliseconds UNIX time. Limited to a 90 day window with respect to startMs and endMs

endMs
required
integer

End of the time range, specified in milliseconds UNIX time.

Responses

Response samples

Content type
application/json
{
  • "trips": [
    ]
}

/fleet/vehicles/locations

Fetch locations for all vehicles between a start/end time. The maximum query duration is 30 minutes (1800000 ms).

query Parameters
startMs
required
integer

Time in Unix epoch milliseconds for the start of the query (cannot exceed 30 minutes)

endMs
required
integer

Time in Unix epoch milliseconds for the end of the query (cannot exceed 30 minutes)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/vehicles/stats

Fetch engine state and aux input data for all vehicles between a start/end time. This endpoint provides the current state of all vehicles, not just the state changes, during the requested time period. Data returned may be affected by device connectivity and processing time.

query Parameters
startMs
required
integer

Time in Unix epoch milliseconds for the start of the query.

endMs
required
integer

Time in Unix epoch milliseconds for the end of the query.

series
string
Enum: "engineState" "auxInput1" "auxInput2"

Comma-separated list of stat types. Options are engineState, auxInput1, and auxInput2. If this parameter is excluded, all 3 stat types will be returned. Example: series=engineState,auxInput2

tagIds
string

Comma-separated list of tag ids. Example: tagIds=1,2,3

startingAfter
string

Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'endingBefore' parameter.

endingBefore
string

Pagination parameter indicating the cursor position to return results before. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'startingAfter' parameter.

limit
number <int64>

Pagination parameter indicating the number of results to return in this request. Used in conjunction with either 'startingAfter' or 'endingBefore'.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "vehicleStats": [
    ]
}

/fleet/vehicles/{vehicleId}/safety/harsh_event

Fetch harsh event details for a vehicle.

path Parameters
vehicleId
required
integer <int64>

ID of the vehicle. Must contain only digits 0-9.

query Parameters
timestamp
required
integer <int64>

Timestamp in milliseconds representing the timestamp of a harsh event.

Responses

Response samples

Content type
application/json
{}

/fleet/vehicles/{vehicleId}/safety/score

Fetch the safety score for the vehicle.

path Parameters
vehicleId
required
integer <int64>

ID of the vehicle. Must contain only digits 0-9.

query Parameters
startMs
required
integer <int64>

Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs. Total duration (endMs - startMs) must be greater than or equal to 1 hour.

endMs
required
integer <int64>

Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs. Total duration (endMs - startMs) must be greater than or equal to 1 hour.

Responses

Response samples

Content type
application/json
{
  • "crashCount": 0,
  • "harshAccelCount": 1,
  • "harshBrakingCount": 2,
  • "harshEvents": [
    ],
  • "harshTurningCount": 0,
  • "safetyScore": 97,
  • "safetyScoreRank": "26",
  • "timeOverSpeedLimitMs": 3769,
  • "totalDistanceDrivenMeters": 291836,
  • "totalHarshEventCount": 3,
  • "totalTimeDrivenMs": 19708293,
  • "vehicleId": 4321
}

/fleet/vehicles/{vehicle_id or external_id}

Gets a specific vehicle.

path Parameters
vehicle_id_or_external_id
required
string

ID of the vehicle. 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, or automatically populated by fields on the vehicle. To specify an external ID as part of a path parameter, use the following format: key:value. For example, maintenanceId:250020. Automatically populated external IDs are prefixed with samsara.. For example, samsara.vin:1HGBH41JXMN109186.

Responses

Response samples

Content type
application/json
{
  • "ExternalIds": {
    },
  • "HarshAccelSetting": "Heavy",
  • "Id": 112,
  • "Name": "Truck A7",
  • "VehicleInfo": {
    }
}

/fleet/vehicles/{vehicle_id or external_id}

Updates the specified vehicle using JSON merge patch format. See IETF RFC 7396: https://tools.ietf.org/html/rfc7396.

path Parameters
vehicle_id_or_external_id
required
string

ID of the vehicle. 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, or automatically populated by fields on the vehicle. To specify an external ID as part of a path parameter, use the following format: key:value. For example, maintenanceId:250020. Automatically populated external IDs are prefixed with samsara.. For example, samsara.vin:1HGBH41JXMN109186.

Request Body schema:
object
harsh_accel_setting
integer <string>
Enum: "Passenger" "Light Truck" "Heavy" "Off" "Auto"

Harsh Event Detection Setting

  • 0: Passenger
  • 1: Light Truck
  • 2: Heavy
  • 3: Off
  • 4: Automatic
name
string

Name

Responses

Request samples

Content type
{
  • "externalIds": {
    },
  • "harsh_accel_setting": "Passenger",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "ExternalIds": {
    },
  • "HarshAccelSetting": "Heavy",
  • "Id": 112,
  • "Name": "Truck A7",
  • "VehicleInfo": {
    }
}

/fleet/vehicles/{vehicle_id}/dispatch/routes

List all routes scheduled within a given time period for the given vehicle. Routes are returned if both of the following conditions are met:

  • The route's scheduled_start_ms is before the timestamp: end_time (defaults to now)
  • The route's scheduled_end_ms is after the timestamp: end_time - duration (defaults to now - 24 hours)

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.

path Parameters
vehicle_id
required
integer <int64>

ID of the vehicle with the associated routes. Must contain only digits 0-9.

query Parameters
end_time
integer <int64>

Time in unix milliseconds that represents the end time of the requested time interval. See above for a description of how routes are returned. Defaults to now.

duration
integer <int64>

Time in milliseconds that represents the duration before end_time to query. Defaults to 24 hours.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/vehicles/{vehicle_id}/dispatch/routes

Create a new dispatch route for the vehicle with vehicle_id.

path Parameters
vehicle_id
required
integer <int64>

ID of the vehicle with the associated routes. Must contain only digits 0-9.

Request Body schema: application/json
required
Array of objects (DispatchJobCreate)

The dispatch jobs to create for this route.

complete_last_stop_on_arrival
boolean
Default: true

When set to true (default), this causes the Route to complete on arrival at the final stop. When set to false, the last stop will capture arrival and departure separately as with other stops.

driver_id
integer <int64>

ID of the driver assigned to the dispatch route. Note that driver_id and vehicle_id are mutually exclusive. If neither is specified, then the route is unassigned.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

name
required
string

Descriptive name of this route.

notes
string

Notes regarding the details of this route; maximum of 2000 characters; newline characters ('\n')can be used for formatting.

scheduled_end_ms
integer <int64>

The time in Unix epoch milliseconds that the last job in the route is scheduled to end.

scheduled_meters
integer <int64>

The distance expected to be traveled for this route in meters.

scheduled_start_ms
required
integer <int64>

The time in Unix epoch milliseconds that the route is scheduled to start.

start_location_address
string

The address of the route's starting location, as it would be recognized if provided to maps.google.com. Optional if a valid start location address ID is provided.

start_location_address_id
integer <int64>

ID of the start location associated with an address book entry. Optional if valid values are provided for start location address and latitude/longitude. If a valid start location address ID is provided, address/latitude/longitude will be used from the address book entry. Name of the address book entry will only be used if the start location name is not provided.

start_location_lat
number <double>

Latitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_lng
number <double>

Longitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_name
string

The name of the route's starting location. If provided, it will take precedence over the name of the address book entry.

trailer_id
integer <int64>

ID of the trailer assigned to the dispatch route. Note that trailers can only be assigned to routes that have a Vehicle or Driver assigned to them.

vehicle_id
integer <int64>

ID of the vehicle assigned to the dispatch route. Note that vehicle_id and driver_id are mutually exclusive. If neither is specified, then the route is unassigned.

Responses

Request samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

Response samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": 556,
  • "actual_end_ms": 1462882101000,
  • "actual_start_ms": 1462882098000,
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "group_id": 101,
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "odometer_end_meters": 2000000,
  • "odometer_start_meters": 1000000,
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

/fleet/vehicles/{vehicle_id}/locations

Fetch locations for a given vehicle between a start/end time. The maximum query duration is one hour.

path Parameters
vehicle_id
required
integer <int64>

ID of the vehicle with the associated routes. Must contain only digits 0-9.

query Parameters
startMs
required
integer <int64>

Time in Unix epoch milliseconds for the start of the query (cannot exceed 1 hour)

endMs
required
integer <int64>

Time in Unix epoch milliseconds for the end of the query (cannot exceed 1 hour)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Industrial

Access to industrial data

/industrial/data

Fetch all of the data inputs.

query Parameters
startMs
integer <int64>

Timestamp in unix milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs. defaults to nowMs.

endMs
integer <int64>

Timestamp in unix milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs. Defaults to nowMs.

Responses

Response samples

Content type
application/json
{
  • "dataInputs": [
    ]
}

/industrial/data/{data_input_id}

Fetch datapoints from a given data input.

path Parameters
data_input_id
required
integer <int64>

ID of the data input. Must contain only digits 0-9.

query Parameters
startMs
integer <int64>

Timestamp in unix milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs. defaults to nowMs.

endMs
integer <int64>

Timestamp in unix milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs. Defaults to nowMs.

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "name": "Pump Flow",
  • "points": [
    ]
}

/industrial/vision/cameras

Fetch all cameras.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/industrial/vision/cameras/{camera_id}/programs

Fetch configured programs on the camera.

path Parameters
camera_id
required
integer <int64>

The camera_id should be valid for the given accessToken.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/industrial/vision/run/camera/{camera_id}

Fetch the latest run for a camera or program by default. If startedAtMs is supplied, fetch the specific run that corresponds to that start time.

path Parameters
camera_id
required
integer <int64>

The camera_id should be valid for the given accessToken.

query Parameters
program_id
integer <int64>

The configured program's ID on the camera.

startedAtMs
integer <int64>

EndMs is an optional param. It will default to the current time.

include
string

Include is a filter parameter. Accepts 'pass', 'reject' or 'no_read'.

limit
integer <int64>

Limit is an integer value from 1 to 1,000.

Responses

Response samples

Content type
application/json
{
  • "cameraId": 1234512345123,
  • "endedAtMs": 0,
  • "inspectionResults": [
    ],
  • "isOngoing": true,
  • "program": {
    },
  • "runSummary": {
    },
  • "startedAtMs": 1553808606097
}

/industrial/vision/runs

Fetch runs.

query Parameters
durationMs
required
integer <int64>

DurationMs is a required param. This works with the EndMs parameter. Indicates the duration in which the visionRuns will be fetched

endMs
integer <int64>

EndMs is an optional param. It will default to the current time.

Responses

Response samples

Content type
application/json
{
  • "visionRuns": [
    ]
}

/industrial/vision/runs/{camera_id}

Fetch runs by camera.

path Parameters
camera_id
required
integer <int64>

The camera_id should be valid for the given accessToken.

query Parameters
durationMs
required
integer <int64>

DurationMs is a required param. This works with the EndMs parameter. Indicates the duration in which the visionRuns will be fetched

endMs
integer <int64>

EndMs is an optional param. It will default to the current time.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/industrial/vision/runs/{camera_id}/{program_id}/{started_at_ms}

Fetch runs by camera and program.

path Parameters
camera_id
required
integer <int64>

The camera_id should be valid for the given accessToken.

program_id
required
integer <int64>

The configured program's ID on the camera.

started_at_ms
required
integer <int64>

Started_at_ms is a required param. Indicates the start time of the run to be fetched.

query Parameters
include
string

Include is a filter parameter. Accepts 'pass', 'reject' or 'no_read'.

Responses

Response samples

Content type
application/json
{
  • "deviceId": 1234512345123,
  • "endedAtMs": 0,
  • "programId": 1,
  • "reportMetadata": {
    },
  • "results": [
    ],
  • "startedAtMs": 1553808606097
}

/machines/history

Get historical data for machine objects. This method returns a set of historical data for all machines

Request Body schema: application/json

Time range to query for events

endMs
required
integer

End of the time range, specified in milliseconds UNIX time.

startMs
required
integer

Beginning of the time range, specified in milliseconds UNIX time.

Responses

Request samples

Content type
application/json
{
  • "endMs": 1462881998034,
  • "startMs": 1462878398034
}

Response samples

Content type
application/json
{
  • "machines": [
    ]
}

/machines/list

Get machine objects. This method returns a list of the machine objects in the Samsara Cloud and information about them.

Responses

Response samples

Content type
application/json
{
  • "machines": [
    ]
}

Sensors

Access to sensor data

/sensors/cargo

Get cargo monitor status (empty / full) for requested sensors.

Request Body schema: application/json

List of sensor IDs to query.

sensors
required
Array of integers <int64> [ items <int64 > ]

List of sensor IDs to query.

Responses

Request samples

Content type
application/json
{
  • "sensors": [
    ]
}

Response samples

Content type
application/json
{
  • "groupId": 101,
  • "sensors": [
    ]
}

/sensors/door

Get door monitor status (closed / open) for requested sensors.

Request Body schema: application/json

List of sensor IDs to query.

sensors
required
Array of integers <int64> [ items <int64 > ]

List of sensor IDs to query.

Responses

Request samples

Content type
application/json
{
  • "sensors": [
    ]
}

Response samples

Content type
application/json
{
  • "groupId": 101,
  • "sensors": [
    ]
}

/sensors/history

Get historical data for specified sensors. This method returns a set of historical data for the specified sensors in the specified time range and at the specified time resolution.

Request Body schema: application/json

Time range and resolution, and list of sensor ID, field pairs to query.

endMs
required
integer

End of the time range, specified in milliseconds UNIX time.

fillMissing
string
Default: "withNull"
Enum: "withNull" "withPrevious"
required
Array of objects <= 40 items
startMs
required
integer

Beginning of the time range, specified in milliseconds UNIX time.

stepMs
required
integer

Time resolution for which data should be returned, in milliseconds. Specifying 3600000 will return data at hour intervals.

Responses

Request samples

Content type
application/json
{
  • "endMs": 1462881998034,
  • "fillMissing": "withNull",
  • "series": [
    ],
  • "startMs": 1462878398034,
  • "stepMs": 3600000
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

/sensors/humidity

Get humidity for requested sensors. This method returns the current relative humidity for the requested sensors.

Request Body schema: application/json

List of sensor IDs to query.

sensors
required
Array of integers <int64> [ items <int64 > ]

List of sensor IDs to query.

Responses

Request samples

Content type
application/json
{
  • "sensors": [
    ]
}

Response samples

Content type
application/json
{
  • "groupId": 101,
  • "sensors": [
    ]
}

/sensors/list

Get sensor objects. This method returns a list of the sensor objects in the Samsara Cloud and information about them.

Responses

Response samples

Content type
application/json
{
  • "sensors": [
    ]
}

/sensors/temperature

Get temperature for requested sensors. This method returns the current ambient temperature (and probe temperature if applicable) for the requested sensors.

Request Body schema: application/json

List of sensor IDs to query.

sensors
required
Array of integers <int64> [ items <int64 > ]

List of sensor IDs to query.

Responses

Request samples

Content type
application/json
{
  • "sensors": [
    ]
}

Response samples

Content type
application/json
{
  • "groupId": 101,
  • "sensors": [
    ]
}

Assets

Access to asset specific data

/fleet/assets

Fetch all of the assets.

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ]
}

/fleet/assets/locations

Fetch current locations of all assets.

query Parameters
startingAfter
string

Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'endingBefore' parameter.

endingBefore
string

Pagination parameter indicating the cursor position to return results before. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'startingAfter' parameter.

limit
number <int64>

Pagination parameter indicating the number of results to return in this request. Used in conjunction with either 'startingAfter' or 'endingBefore'.

tagIds
Array of strings

A comma-separated list of tag IDs. Example: tagIds=1000,1001

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "pagination": {
    }
}

/fleet/assets/reefers

Fetches all reefers and reefer-specific stats.

query Parameters
startMs
required
integer <int64>

Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs.

endMs
required
integer <int64>

Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs.

startingAfter
string

Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'endingBefore' parameter.

endingBefore
string

Pagination parameter indicating the cursor position to return results before. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'startingAfter' parameter.

limit
number <int64>

Pagination parameter indicating the number of results to return in this request. Used in conjunction with either 'startingAfter' or 'endingBefore'.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

/fleet/assets/{assetId}/locations

Fetch the historical locations for the asset.

path Parameters
asset_id
required
integer <int64>

ID of the asset. Must contain only digits 0-9.

query Parameters
startMs
required
integer <int64>

Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs.

endMs
required
integer <int64>

Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/assets/{assetId}/reefer

Fetch the reefer-specific stats of an asset.

path Parameters
asset_id
required
integer <int64>

ID of the asset. Must contain only digits 0-9.

query Parameters
startMs
required
integer <int64>

Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs.

endMs
required
integer <int64>

Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs.

Responses

Response samples

Content type
application/json
{
  • "assetType": "Thermo King",
  • "id": 1,
  • "name": "Reefer 123",
  • "reeferStats": {
    }
}

Safety

Access to safety specific data

/fleet/drivers/{driverId}/safety/score

Fetch the safety score for the driver.

path Parameters
driverId
required
integer <int64>

ID of the driver. Must contain only digits 0-9.

query Parameters
startMs
required
integer <int64>

Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs. Total duration (endMs - startMs) must be greater than or equal to 1 hour.

endMs
required
integer <int64>

Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs. Total duration (endMs - startMs) must be greater than or equal to 1 hour.

Responses

Response samples

Content type
application/json
{
  • "crashCount": 0,
  • "driverId": 1234,
  • "harshAccelCount": 1,
  • "harshBrakingCount": 2,
  • "harshEvents": [
    ],
  • "harshTurningCount": 0,
  • "safetyScore": 97,
  • "safetyScoreRank": "26",
  • "timeOverSpeedLimitMs": 3769,
  • "totalDistanceDrivenMeters": 291836,
  • "totalHarshEventCount": 3,
  • "totalTimeDrivenMs": 19708293
}

/fleet/vehicles/{vehicleId}/safety/harsh_event

Fetch harsh event details for a vehicle.

path Parameters
vehicleId
required
integer <int64>

ID of the vehicle. Must contain only digits 0-9.

query Parameters
timestamp
required
integer <int64>

Timestamp in milliseconds representing the timestamp of a harsh event.

Responses

Response samples

Content type
application/json
{}

/fleet/vehicles/{vehicleId}/safety/score

Fetch the safety score for the vehicle.

path Parameters
vehicleId
required
integer <int64>

ID of the vehicle. Must contain only digits 0-9.

query Parameters
startMs
required
integer <int64>

Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs. Total duration (endMs - startMs) must be greater than or equal to 1 hour.

endMs
required
integer <int64>

Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs. Total duration (endMs - startMs) must be greater than or equal to 1 hour.

Responses

Response samples

Content type
application/json
{
  • "crashCount": 0,
  • "harshAccelCount": 1,
  • "harshBrakingCount": 2,
  • "harshEvents": [
    ],
  • "harshTurningCount": 0,
  • "safetyScore": 97,
  • "safetyScoreRank": "26",
  • "timeOverSpeedLimitMs": 3769,
  • "totalDistanceDrivenMeters": 291836,
  • "totalHarshEventCount": 3,
  • "totalTimeDrivenMs": 19708293,
  • "vehicleId": 4321
}

Users

Access to user data

/user_roles

Get all roles in the organization.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/users

List all users in the organization.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/users

Add a user to the organization.

Request Body schema: application/json

User properties. Only one of organizationRoleId or tagRoles is required.

authType
required
string
Enum: "default" "saml"

The authentication type the user uses to authenticate. To use SAML this organization must have a configured SAML integration.

name
required
string

The first and last name of the user.

organizationRoleId
string

The id of the role the user is assigned to at the organization level. This will be blank for users that only have access to specific tags.

Array of objects

If specified, the user will be an administrator for these tags. If left blank, the user has access to the entire organization.

email
required
string

The email address of this user.

Responses

Request samples

Content type
application/json
{
  • "authType": "default",
  • "name": "Jane Doe",
  • "organizationRoleId": "23d4d8d3-dc10-4e7a-a183-69968751f23e",
  • "tagRoles": [
    ],
  • "email": "user@company.com"
}

Response samples

Content type
application/json
{
  • "authType": "default",
  • "email": "user@company.com",
  • "name": "Jane Doe",
  • "organizationRoleId": "23d4d8d3-dc10-4e7a-a183-69968751f23e",
  • "id": 123,
  • "organizationRole": "Full Admin",
  • "tagRoles": [
    ]
}

/users/{userId}

Get a user.

path Parameters
userId
required
integer <int64>

ID of the user. Must contain only digits 0-9.

Request Body schema: application/json

User properties. Only one of organizationRoleId or tagRoles is required.

authType
required
string
Enum: "default" "saml"

The authentication type the user uses to authenticate. To use SAML this organization must have a configured SAML integration.

name
required
string

The first and last name of the user.

organizationRoleId
string

The id of the role the user is assigned to at the organization level. This will be blank for users that only have access to specific tags.

Array of objects

If specified, the user will be an administrator for these tags. If left blank, the user has access to the entire organization.

email
required
string

The email address of this user.

Responses

Request samples

Content type
application/json
{
  • "authType": "default",
  • "name": "Jane Doe",
  • "organizationRoleId": "23d4d8d3-dc10-4e7a-a183-69968751f23e",
  • "tagRoles": [
    ],
  • "email": "user@company.com"
}

Response samples

Content type
application/json
{
  • "authType": "default",
  • "email": "user@company.com",
  • "name": "Jane Doe",
  • "organizationRoleId": "23d4d8d3-dc10-4e7a-a183-69968751f23e",
  • "id": 123,
  • "organizationRole": "Full Admin",
  • "tagRoles": [
    ]
}

/users/{userId}

Remove a user from the organization.

path Parameters
userId
required
integer <int64>

ID of the user. Must contain only digits 0-9.

Responses

Response samples

Content type
application/json
"string"

/users/{userId}

Update some fields on a user. Only fields to be changed need to be supplied. Note that if you change an object or collection, you must supply the complete collection. For example, to add a tag role to a user, you must specify all tag roles that the user should have.

path Parameters
userId
required
integer <int64>

ID of the user. Must contain only digits 0-9.

Request Body schema: application/json

User properties. Note that when updating tagRoles, the complete list of tag roles must be supplied for the user. To delete all tag roles set the value to null or an empty array.

authType
string
Enum: "default" "saml"

The authentication type the user uses to authenticate. To use SAML this organization must have a configured SAML integration.

name
string

The first and last name of the user.

organizationRoleId
string

The id of the role the user is assigned to at the organization level. This will be blank for users that only have access to specific tags.

Array of objects

If specified, the user will be an administrator for these tags. If left blank, the user has access to the entire organization.

Responses

Request samples

Content type
application/json
{
  • "authType": "default",
  • "name": "Jane Doe",
  • "organizationRoleId": "23d4d8d3-dc10-4e7a-a183-69968751f23e",
  • "tagRoles": [
    ]
}

Response samples

Content type
application/json
{
  • "authType": "default",
  • "email": "user@company.com",
  • "name": "Jane Doe",
  • "organizationRoleId": "23d4d8d3-dc10-4e7a-a183-69968751f23e",
  • "id": 123,
  • "organizationRole": "Full Admin",
  • "tagRoles": [
    ]
}

Contacts

Contacts can be setup in order to send alerts via SMS text or email to individuals in your organization. You can retrieve a list of all contacts, or you can fetch each contact individually.

/contacts

Fetch all contacts for the organization.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/contacts

Add a contact to the organization.

Request Body schema: application/json

Add a contact.

email
string

Email address of the contact.

firstName
string

First name of the contact.

lastName
string

Last name of the contact.

phone
string

Phone number of the contact.

Responses

Request samples

Content type
application/json
{
  • "email": "jane.jones@yahoo.com",
  • "firstName": "Jane",
  • "lastName": "Jones",
  • "phone": "111-222-3344"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

/contacts/{contact_id}

Fetch a contact by its id.

path Parameters
contact_id
required
integer <int64>

ID of the contact. Must contain only digits 0-9.

Responses

Response samples

Content type
application/json
{
  • "email": "jane.jones@yahoo.com",
  • "firstName": "Jane",
  • "id": 123,
  • "lastName": "Jones",
  • "phone": "111-222-3344"
}

/contacts/{contact_id}

Remove a contact from the organization.

path Parameters
contact_id
required
integer <int64>

ID of the contact. Must contain only digits 0-9.

Responses

Response samples

Content type
application/json
"string"

/contacts/{contact_id}

Update the name, phone number or email of a contact using the contact id. Only fields to be changed need to be supplied.

path Parameters
contact_id
required
integer <int64>

ID of the contact. Must contain only digits 0-9.

Request Body schema: application/json

Update the email, first name, last name, or phone number of a contact using the contact_id.

email
string

Email address of the contact.

firstName
string

First name of the contact.

lastName
string

Last name of the contact.

phone
string

Phone number of the contact.

Responses

Request samples

Content type
application/json
{
  • "email": "jane.jones@yahoo.com",
  • "firstName": "Jane",
  • "lastName": "Jones",
  • "phone": "111-222-3344"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Routes

/fleet/dispatch/routes

List all routes scheduled within a given time period. Routes are returned if both of the following conditions are met:

  • The route's scheduled_start_ms is before the timestamp: end_time (defaults to now)
  • The route's scheduled_end_ms is after the timestamp: end_time - duration (defaults to now - 24 hours)

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.

query Parameters
end_time
integer <int64>

Time in unix milliseconds that represents the end time of the requested time interval. See above for a description of how routes are returned. Defaults to now.

duration
integer <int64>

Time in milliseconds that represents the duration before end_time to query. Defaults to 24 hours.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/dispatch/routes

Create a new dispatch route.

Request Body schema: application/json
required
Array of objects (DispatchJobCreate)

The dispatch jobs to create for this route.

complete_last_stop_on_arrival
boolean
Default: true

When set to true (default), this causes the Route to complete on arrival at the final stop. When set to false, the last stop will capture arrival and departure separately as with other stops.

driver_id
integer <int64>

ID of the driver assigned to the dispatch route. Note that driver_id and vehicle_id are mutually exclusive. If neither is specified, then the route is unassigned.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

name
required
string

Descriptive name of this route.

notes
string

Notes regarding the details of this route; maximum of 2000 characters; newline characters ('\n')can be used for formatting.

scheduled_end_ms
integer <int64>

The time in Unix epoch milliseconds that the last job in the route is scheduled to end.

scheduled_meters
integer <int64>

The distance expected to be traveled for this route in meters.

scheduled_start_ms
required
integer <int64>

The time in Unix epoch milliseconds that the route is scheduled to start.

start_location_address
string

The address of the route's starting location, as it would be recognized if provided to maps.google.com. Optional if a valid start location address ID is provided.

start_location_address_id
integer <int64>

ID of the start location associated with an address book entry. Optional if valid values are provided for start location address and latitude/longitude. If a valid start location address ID is provided, address/latitude/longitude will be used from the address book entry. Name of the address book entry will only be used if the start location name is not provided.

start_location_lat
number <double>

Latitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_lng
number <double>

Longitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_name
string

The name of the route's starting location. If provided, it will take precedence over the name of the address book entry.

trailer_id
integer <int64>

ID of the trailer assigned to the dispatch route. Note that trailers can only be assigned to routes that have a Vehicle or Driver assigned to them.

vehicle_id
integer <int64>

ID of the vehicle assigned to the dispatch route. Note that vehicle_id and driver_id are mutually exclusive. If neither is specified, then the route is unassigned.

Responses

Request samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

Response samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": 556,
  • "actual_end_ms": 1462882101000,
  • "actual_start_ms": 1462882098000,
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "group_id": 101,
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "odometer_end_meters": 2000000,
  • "odometer_start_meters": 1000000,
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

/fleet/dispatch/routes/job_updates

Fetch all updates to a job including route data in the last 24 hours or subsequent to an sequence ID. Returns a maximum of 500 job updates. If more than 500 job updates are available, another request made with the prior request's sequence_id will return the next set of available job updates.

query Parameters
sequence_id
string

Sequence ID from the response payload of the last request. Defaults to fetching updates from last 24 hours.

include
string

Optionally set include=route to include route object in response payload.

Responses

Response samples

Content type
application/json
{
  • "job_updates": [
    ],
  • "sequence_id": "eyJpZCI6MywiY3JlYXRlZF9hdCI6MTQ5OTQyOTIyMDAwMn0="
}

/fleet/dispatch/routes/{route_id}

Fetch a dispatch route by id.

path Parameters
route_id_or_external_id
required
string

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

Responses

Response samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": 556,
  • "actual_end_ms": 1462882101000,
  • "actual_start_ms": 1462882098000,
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "group_id": 101,
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "odometer_end_meters": 2000000,
  • "odometer_start_meters": 1000000,
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

/fleet/dispatch/routes/{route_id}/

Update the dispatch route. Examples of this include:

  • Adding, removing, and/or editing jobs in the dispatch_jobs array. If you add a job to this array, you do not need to include an id field. One will be created automatically for that new job.
  • Updating the assigned driver or vehicle. (Routes may be assigned to a driver or a vehicle, but not both).
  • Updating the location and/or timing information of the route.
path Parameters
route_id_or_external_id
required
string

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 schema: application/json
required
Array of objects (DispatchJobUpdate)

The dispatch jobs for the route.

id
required
integer <int64>

ID of route. This must match the route ID passed in URL.

complete_last_stop_on_arrival
boolean
Default: true

When set to true (default), this causes the Route to complete on arrival at the final stop. When set to false, the last stop will capture arrival and departure separately as with other stops.

driver_id
integer <int64>

ID of the driver assigned to the dispatch route. Note that driver_id and vehicle_id are mutually exclusive. If neither is specified, then the route is unassigned.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

name
required
string

Descriptive name of this route.

notes
string

Notes regarding the details of this route; maximum of 2000 characters; newline characters ('\n')can be used for formatting.

scheduled_end_ms
integer <int64>

The time in Unix epoch milliseconds that the last job in the route is scheduled to end.

scheduled_meters
integer <int64>

The distance expected to be traveled for this route in meters.

scheduled_start_ms
required
integer <int64>

The time in Unix epoch milliseconds that the route is scheduled to start.

start_location_address
string

The address of the route's starting location, as it would be recognized if provided to maps.google.com. Optional if a valid start location address ID is provided.

start_location_address_id
integer <int64>

ID of the start location associated with an address book entry. Optional if valid values are provided for start location address and latitude/longitude. If a valid start location address ID is provided, address/latitude/longitude will be used from the address book entry. Name of the address book entry will only be used if the start location name is not provided.

start_location_lat
number <double>

Latitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_lng
number <double>

Longitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_name
string

The name of the route's starting location. If provided, it will take precedence over the name of the address book entry.

trailer_id
integer <int64>

ID of the trailer assigned to the dispatch route. Note that trailers can only be assigned to routes that have a Vehicle or Driver assigned to them.

vehicle_id
integer <int64>

ID of the vehicle assigned to the dispatch route. Note that vehicle_id and driver_id are mutually exclusive. If neither is specified, then the route is unassigned.

Responses

Request samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": "42",
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

Response samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": 556,
  • "actual_end_ms": 1462882101000,
  • "actual_start_ms": 1462882098000,
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "group_id": 101,
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "odometer_end_meters": 2000000,
  • "odometer_start_meters": 1000000,
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

/fleet/dispatch/routes/{route_id}/

Delete a dispatch route and its associated jobs.

path Parameters
route_id_or_external_id
required
string

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 schema: application/json
apply_to_future_routes
boolean

This is only for a recurring route. If set to true, delete all following runs of the route. If set to false, only delete the current route.

Responses

Request samples

Content type
application/json
{
  • "apply_to_future_routes": true
}

Response samples

Content type
application/json
"string"

/fleet/dispatch/routes/{route_id}/history

Fetch the history of a dispatch route.

path Parameters
route_id_or_external_id
required
string

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

query Parameters
start_time
integer <int64>

Timestamp representing the start of the period to fetch, inclusive. Used in combination with end_time. Defaults to 0.

end_time
integer <int64>

Timestamp representing the end of the period to fetch, inclusive. Used in combination with start_time. Defaults to nowMs.

Responses

Response samples

Content type
application/json
{
  • "history": [
    ]
}

/fleet/drivers/{driver_id}/dispatch/routes

List all routes scheduled within a given time period for the given driver. Routes are returned if both of the following conditions are met:

  • The route's scheduled_start_ms is before the timestamp: end_time (defaults to now)
  • The route's scheduled_end_ms is after the timestamp: end_time - duration (defaults to now - 24 hours)

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.

path Parameters
driver_id
required
integer <int64>

ID of the driver with the associated routes. Must contain only digits 0-9.

query Parameters
end_time
integer <int64>

Time in unix milliseconds that represents the end time of the requested time interval. See above for a description of how routes are returned. Defaults to now.

duration
integer <int64>

Time in milliseconds that represents the duration before end_time to query. Defaults to 24 hours.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/drivers/{driver_id}/dispatch/routes

Create a new dispatch route for the driver with driver_id.

path Parameters
driver_id
required
integer <int64>

ID of the driver with the associated routes. Must contain only digits 0-9.

Request Body schema: application/json
required
Array of objects (DispatchJobCreate)

The dispatch jobs to create for this route.

complete_last_stop_on_arrival
boolean
Default: true

When set to true (default), this causes the Route to complete on arrival at the final stop. When set to false, the last stop will capture arrival and departure separately as with other stops.

driver_id
integer <int64>

ID of the driver assigned to the dispatch route. Note that driver_id and vehicle_id are mutually exclusive. If neither is specified, then the route is unassigned.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

name
required
string

Descriptive name of this route.

notes
string

Notes regarding the details of this route; maximum of 2000 characters; newline characters ('\n')can be used for formatting.

scheduled_end_ms
integer <int64>

The time in Unix epoch milliseconds that the last job in the route is scheduled to end.

scheduled_meters
integer <int64>

The distance expected to be traveled for this route in meters.

scheduled_start_ms
required
integer <int64>

The time in Unix epoch milliseconds that the route is scheduled to start.

start_location_address
string

The address of the route's starting location, as it would be recognized if provided to maps.google.com. Optional if a valid start location address ID is provided.

start_location_address_id
integer <int64>

ID of the start location associated with an address book entry. Optional if valid values are provided for start location address and latitude/longitude. If a valid start location address ID is provided, address/latitude/longitude will be used from the address book entry. Name of the address book entry will only be used if the start location name is not provided.

start_location_lat
number <double>

Latitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_lng
number <double>

Longitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_name
string

The name of the route's starting location. If provided, it will take precedence over the name of the address book entry.

trailer_id
integer <int64>

ID of the trailer assigned to the dispatch route. Note that trailers can only be assigned to routes that have a Vehicle or Driver assigned to them.

vehicle_id
integer <int64>

ID of the vehicle assigned to the dispatch route. Note that vehicle_id and driver_id are mutually exclusive. If neither is specified, then the route is unassigned.

Responses

Request samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

Response samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": 556,
  • "actual_end_ms": 1462882101000,
  • "actual_start_ms": 1462882098000,
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "group_id": 101,
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "odometer_end_meters": 2000000,
  • "odometer_start_meters": 1000000,
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

/fleet/vehicles/{vehicle_id}/dispatch/routes

List all routes scheduled within a given time period for the given vehicle. Routes are returned if both of the following conditions are met:

  • The route's scheduled_start_ms is before the timestamp: end_time (defaults to now)
  • The route's scheduled_end_ms is after the timestamp: end_time - duration (defaults to now - 24 hours)

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.

path Parameters
vehicle_id
required
integer <int64>

ID of the vehicle with the associated routes. Must contain only digits 0-9.

query Parameters
end_time
integer <int64>

Time in unix milliseconds that represents the end time of the requested time interval. See above for a description of how routes are returned. Defaults to now.

duration
integer <int64>

Time in milliseconds that represents the duration before end_time to query. Defaults to 24 hours.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/vehicles/{vehicle_id}/dispatch/routes

Create a new dispatch route for the vehicle with vehicle_id.

path Parameters
vehicle_id
required
integer <int64>

ID of the vehicle with the associated routes. Must contain only digits 0-9.

Request Body schema: application/json
required
Array of objects (DispatchJobCreate)

The dispatch jobs to create for this route.

complete_last_stop_on_arrival
boolean
Default: true

When set to true (default), this causes the Route to complete on arrival at the final stop. When set to false, the last stop will capture arrival and departure separately as with other stops.

driver_id
integer <int64>

ID of the driver assigned to the dispatch route. Note that driver_id and vehicle_id are mutually exclusive. If neither is specified, then the route is unassigned.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

name
required
string

Descriptive name of this route.

notes
string

Notes regarding the details of this route; maximum of 2000 characters; newline characters ('\n')can be used for formatting.

scheduled_end_ms
integer <int64>

The time in Unix epoch milliseconds that the last job in the route is scheduled to end.

scheduled_meters
integer <int64>

The distance expected to be traveled for this route in meters.

scheduled_start_ms
required
integer <int64>

The time in Unix epoch milliseconds that the route is scheduled to start.

start_location_address
string

The address of the route's starting location, as it would be recognized if provided to maps.google.com. Optional if a valid start location address ID is provided.

start_location_address_id
integer <int64>

ID of the start location associated with an address book entry. Optional if valid values are provided for start location address and latitude/longitude. If a valid start location address ID is provided, address/latitude/longitude will be used from the address book entry. Name of the address book entry will only be used if the start location name is not provided.

start_location_lat
number <double>

Latitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_lng
number <double>

Longitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.

start_location_name
string

The name of the route's starting location. If provided, it will take precedence over the name of the address book entry.

trailer_id
integer <int64>

ID of the trailer assigned to the dispatch route. Note that trailers can only be assigned to routes that have a Vehicle or Driver assigned to them.

vehicle_id
integer <int64>

ID of the vehicle assigned to the dispatch route. Note that vehicle_id and driver_id are mutually exclusive. If neither is specified, then the route is unassigned.

Responses

Request samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

Response samples

Content type
application/json
{
  • "dispatch_jobs": [
    ],
  • "id": 556,
  • "actual_end_ms": 1462882101000,
  • "actual_start_ms": 1462882098000,
  • "complete_last_stop_on_arrival": true,
  • "driver_id": 555,
  • "externalIds": {
    },
  • "group_id": 101,
  • "name": "Bid #123",
  • "notes": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23.",
  • "odometer_end_meters": 2000000,
  • "odometer_start_meters": 1000000,
  • "scheduled_end_ms": 1462881998034,
  • "scheduled_meters": 10000,
  • "scheduled_start_ms": 1462881998034,
  • "start_location_address": "123 Main St, Philadelphia, PA 19106",
  • "start_location_address_id": 67890,
  • "start_location_lat": 123.456,
  • "start_location_lng": 37.459,
  • "start_location_name": "ACME Inc. Philadelphia HQ",
  • "trailer_id": 666,
  • "vehicle_id": 444
}

Drivers

/fleet/drivers/create

Create a new driver.

Request Body schema: application/json

Driver creation body

password
required
string

Driver's password for the driver app.

tagIds
Array of numbers <int64> (TagIds) [ items <int64 > ]

A list of tag IDs.

eldAdverseWeatherExemptionEnabled
boolean

Flag indicating this driver may use Adverse Weather exemptions in ELD logs.

eldBigDayExemptionEnabled
boolean

Flag indicating this driver may use Big Day excemptions in ELD logs.

eldDayStartHour
integer

0 indicating midnight-to-midnight ELD driving hours, 12 to indicate noon-to-noon driving hours.

eldExempt
boolean

Flag indicating this driver is exempt from the Electronic Logging Mandate.

eldExemptReason
string

Reason that this driver is exempt from the Electronic Logging Mandate (see eldExempt).

eldPcEnabled
boolean
Default: false

Flag indicating this driver may select the Personal Conveyance duty status in ELD logs.

eldYmEnabled
boolean
Default: false

Flag indicating this driver may select the Yard Move duty status in ELD logs.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

groupId
integer <int64>

Deprecated.

licenseNumber
string

Driver's state issued license number.

licenseState
string

Abbreviation of state that issued driver's license.

name
required
string

Driver's name.

notes
string

Notes about the driver.

phone
string

Driver's phone number. Please include only digits, ex. 4157771234

timezone
string

Home terminal timezone, in order to indicate what time zone should be used to calculate the ELD logs. Driver timezones use IANA timezone database keys (e.g. America/Los_Angeles, America/New_York, Europe/London, etc.). You can find a mapping of common timezone formats to IANA timezone keys here.

username
string

Driver's login username into the driver app. The username may not contain spaces or @.

vehicleGroupTagId
integer <int64>

ID of the tag which determines which vehicles a driver will see when selecting vehicles

vehicleId
integer <int64>

ID of the vehicle assigned to the driver for static vehicle assignments. (uncommon).

Responses

Request samples

Content type
application/json
{
  • "password": "mypassword",
  • "tagIds": [
    ],
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

Response samples

Content type
application/json
{
  • "id": 556,
  • "isDeactivated": true,
  • "tags": [
    ],
  • "currentVehicleId": 879,
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

/fleet/drivers/inactive

Get all inactive drivers. When drivers leave an organization, you can deactivate them. You can use DELETE /v1/fleet/drivers/{id} to deactivate drivers. Inactive driver records will still be part of reports such as Hours of Service.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/fleet/drivers/inactive/{driver_id or external_id}

Get an inactive driver. When drivers leave an organization, you can deactivate them. You can use DELETE /v1/fleet/drivers/{id} to deactivate drivers. You can use PUT /v1/fleet/drivers/{id} to reactivate drivers. Inactive driver records will still be part of reports such as Hours of Service.

path Parameters
driver_id_or_external_id
required
string

ID of the driver. 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

Responses

Response samples

Content type
application/json
{
  • "id": 556,
  • "isDeactivated": true,
  • "tags": [
    ],
  • "currentVehicleId": 879,
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

/fleet/drivers/inactive/{driver_id or external_id}

Reactivate a driver.

path Parameters
driver_id_or_external_id
required
string

ID of the driver. 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 schema: application/json

Driver reactivation body

reactivate
required
boolean

True indicates that this driver should be reactivated.

Responses

Request samples

Content type
application/json
{
  • "reactivate": true
}

Response samples

Content type
application/json
{
  • "id": 556,
  • "isDeactivated": true,
  • "tags": [
    ],
  • "currentVehicleId": 879,
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

/fleet/drivers/{driver_id or external_id}

Get an active driver. When drivers leave an organization, you can deactivate them. Use GET /v1/fleet/drivers/inactive/{id} to get an inactive driver, and use DELETE /v1/fleet/drivers/{id} to deactivate drivers.

path Parameters
driver_id_or_external_id
required
string

ID of the driver. 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

Responses

Response samples

Content type
application/json
{
  • "id": 556,
  • "isDeactivated": true,
  • "tags": [
    ],
  • "currentVehicleId": 879,
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

/fleet/drivers/{driver_id or external_id}

Deactivate a driver. You can use PUT /v1/fleet/drivers/{id} to reactivate a driver.

path Parameters
driver_id_or_external_id
required
string

ID of the driver. 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

Responses

Response samples

Content type
application/json
"string"

/fleet/drivers/{driver_id or external_id}

Update a driver. You can update both active and inactive drivers. Active drivers are drivers that are currently part of your fleet. Inactive drivers are drivers that are not currently part of your fleet. Inactive driver historical data will still be available via different reports such as Hours of Service. Use DELETE /v1/fleet/drivers/{id} to deactivate drivers, and PUT /v1/fleet/drivers/{id} to reactivate drivers.

path Parameters
driver_id_or_external_id
required
string

ID of the driver. 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 schema: application/json

Driver update body

tagIds
Array of numbers <int64> (TagIds) [ items <int64 > ]

A list of tag IDs.

eldAdverseWeatherExemptionEnabled
boolean

Flag indicating this driver may use Adverse Weather exemptions in ELD logs.

eldBigDayExemptionEnabled
boolean

Flag indicating this driver may use Big Day excemptions in ELD logs.

eldDayStartHour
integer

0 indicating midnight-to-midnight ELD driving hours, 12 to indicate noon-to-noon driving hours.

eldExempt
boolean

Flag indicating this driver is exempt from the Electronic Logging Mandate.

eldExemptReason
string

Reason that this driver is exempt from the Electronic Logging Mandate (see eldExempt).

eldPcEnabled
boolean
Default: false

Flag indicating this driver may select the Personal Conveyance duty status in ELD logs.

eldYmEnabled
boolean
Default: false

Flag indicating this driver may select the Yard Move duty status in ELD logs.

object (ExternalIDs)

User-defined dictionary of external IDs (key-value pairs). 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. To delete an external ID, set its value to null or the empty string (""). An external ID can be used as a path parameter to retrieve or update that resource.

groupId
integer <int64>

Deprecated.

licenseNumber
string

Driver's state issued license number.

licenseState
string

Abbreviation of state that issued driver's license.

name
required
string

Driver's name.

notes
string

Notes about the driver.

phone
string

Driver's phone number. Please include only digits, ex. 4157771234

timezone
string

Home terminal timezone, in order to indicate what time zone should be used to calculate the ELD logs. Driver timezones use IANA timezone database keys (e.g. America/Los_Angeles, America/New_York, Europe/London, etc.). You can find a mapping of common timezone formats to IANA timezone keys here.

username
string

Driver's login username into the driver app. The username may not contain spaces or @.

vehicleGroupTagId
integer <int64>

ID of the tag which determines which vehicles a driver will see when selecting vehicles

vehicleId
integer <int64>

ID of the vehicle assigned to the driver for static vehicle assignments. (uncommon).

Responses

Request samples

Content type
application/json
{
  • "tagIds": [
    ],
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

Response samples

Content type
application/json
{
  • "id": 556,
  • "isDeactivated": true,
  • "tags": [
    ],
  • "currentVehicleId": 879,
  • "eldAdverseWeatherExemptionEnabled": true,
  • "eldBigDayExemptionEnabled": true,
  • "eldDayStartHour": 0,
  • "eldExempt": true,
  • "eldExemptReason": "string",
  • "eldPcEnabled": false,
  • "eldYmEnabled": false,
  • "externalIds": {
    },
  • "groupId": 101,
  • "licenseNumber": "E1234567",
  • "licenseState": "CA",
  • "name": "Susan Jones",
  • "notes": "Also goes by the nickname 'Furious Fred'.",
  • "phone": "5558234327",
  • "timezone": "America/Los_Angeles",
  • "username": "SusanJones",
  • "vehicleGroupTagId": 171,
  • "vehicleId": 444
}

Messages

/fleet/messages

Get all messages.

query Parameters
endMs
integer <int64>

Time in unix milliseconds that represents the end of time range of messages to return. Used in combination with durationMs. Defaults to now.

durationMs
integer <int64>

Time in milliseconds that represents the duration before endMs to query. Defaults to 24 hours.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

/fleet/messages

Send a message to a list of driver ids.

Request Body schema: application/json

Text to send to a list of driverIds.

driverIds
required
Array of numbers <int64> [ items <int64 > ]

IDs of the drivers for whom the messages are sent to.

text
required
string <= 2500 characters

The text sent in the message.

Responses

Request samples

Content type
application/json
{
  • "driverIds": [
    ],
  • "text": "This is a message."
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Tags

/tags

Fetch all of the tags.

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

/tags

Create a new tag.

Request Body schema: application/json
Array of objects (TaggedAssetBase)

The assets that belong to this tag.

Array of objects (TaggedDriverBase)

The drivers that belong to this tag.

Array of objects (TaggedMachineBase)

The machines that belong to this tag.

name
required
string

Name of this tag.

parentTagId
integer <int64>

If this tag is part a hierarchical tag tree as a child tag, the parentTagId is the ID of this tag's parent tag.

Array of objects (TaggedSensorBase)

The sensors that belong to this tag.

Array of objects (TaggedVehicleBase)

The vehicles that belong to this tag.

Responses

Request samples

Content type
application/json
{
  • "assets": [
    ],
  • "drivers": [
    ],
  • "machines": [
    ],
  • "name": "Broken Vehicles",
  • "parentTagId": 8389,
  • "sensors": [
    ],
  • "vehicles": [
    ]
}

Response samples

Content type
application/json
{
  • "addresses": [
    ],
  • "assets": [
    ],
  • "drivers": [
    ],
  • "groupId": 2348,
  • "id": 12345,
  • "machines": [
    ],
  • "name": "Broken Vehicles",
  • "parentTagId": 8389,
  • "sensors": [
    ],
  • "vehicles": [
    ]
}

/tags/{tag_id}

Fetch a tag by id.

path Parameters
tag_id
required
integer <int64>

ID of the tag. Must contain only digits 0-9.

Responses

Response samples

Content type
application/json
{
  • "addresses": [
    ],
  • "assets": [
    ],
  • "drivers": [
    ],
  • "groupId": 2348,
  • "id": 12345,
  • "machines": [
    ],
  • "name": "Broken Vehicles",
  • "parentTagId": 8389,
  • "sensors": [
    ],
  • "vehicles": [
    ]
}

/tags/{tag_id}

Update a tag with a new name and new members. This API call would replace all old members of a tag with new members specified in the request body. To modify only a few devices associated with a tag use the PATCH endpoint.

path Parameters
tag_id
required
integer <int64>

ID of the tag. Must contain only digits 0-9.

Request Body schema: application/json
Array of objects (TaggedAssetBase)

The assets that belong to this tag.

Array of objects (TaggedDriverBase)

The drivers that belong to this tag.

Array of objects (TaggedMachineBase)

The machines that belong to this tag.

name
string

Updated name of this tag.

parentTagId
integer <int64>

If this tag is part a hierarchical tag tree as a child tag, the parentTagId is the ID of this tag's parent tag.

Array of objects (TaggedSensorBase)

The sensors that belong to this tag.

Array of objects (TaggedVehicleBase)

The vehicles that belong to this tag.

Responses

Request samples

Content type
application/json
{
  • "assets": [
    ],
  • "drivers": [
    ],
  • "machines": [
    ],
  • "name": "Broken Vehicles",
  • "parentTagId": 8389,
  • "sensors": [
    ],
  • "vehicles": [
    ]
}

Response samples

Content type
application/json
{
  • "addresses": [
    ],
  • "assets": [
    ],
  • "drivers": [
    ],
  • "groupId": 2348,
  • "id": 12345,
  • "machines": [
    ],
  • "name": "Broken Vehicles",
  • "parentTagId": 8389,
  • "sensors": [
    ],
  • "vehicles": [
    ]
}

/tags/{tag_id}

Permanently deletes a tag.

path Parameters
tag_id
required
integer <int64>

ID of the tag. Must contain only digits 0-9.

Responses

Response samples

Content type
application/json
"string"

/tags/{tag_id}

Add or delete specific members from a tag, or modify the name of a tag.

path Parameters
tag_id
required
integer <int64>

ID of the tag. Must contain only digits 0-9.

Request Body schema: application/json
object

Specify devices, etc. that should be added to the tag.

object

Specify devices, etc. that should be removed from the tag.

name
string

Updated name of this tag.

parentTagId
integer <int64>

If this tag is part a hierarchical tag tree as a child tag, the parentTagId is the ID of this tag's parent tag.

Responses

Request samples

Content type
application/json
{
  • "add": {
    },
  • "delete": {
    },
  • "name": "Broken Vehicles",
  • "parentTagId": 8389
}

Response samples

Content type
application/json
{
  • "addresses": [
    ],
  • "assets": [
    ],
  • "drivers": [
    ],
  • "groupId": 2348,
  • "id": 12345,
  • "machines": [
    ],
  • "name": "Broken Vehicles",
  • "parentTagId": 8389,
  • "sensors": [
    ],
  • "vehicles": [
    ]
}