{
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"schemes": [
"https"
],
"swagger": "2.0",
"info": {
"description": "\u003cstyle type=\"text/css\"\u003e\nn {\n padding: 1em;\n width: 100%;\n display: block;\n margin: 28px 0;\n}\nn.info {\n background-color: rgba(0, 51, 160, 0.1);\n}\nn.warning {\n background-color: #fdf6e3;\n}\ni:before {\n margin-right: 6px;\n}\nnh {\n font-size: 1.5rem;\n font-weight: 700;\n line-height: 1.1;\n display: block;\n}\nnb {\n margin-top: 10px;\n padding-left: 22px;\n display: block;\n}\n\u003c/style\u003e\n\n# Overview\n\n\u003cn class=\"info\"\u003e\n\u003cnh\u003e\n\u003ci class=\"fa fa-info-circle\"\u003e\u003c/i\u003e\nNew API Available!\n\u003c/nh\u003e\n\u003cnb\u003e\nSamsara 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).\n\u003c/nb\u003e\n\u003c/n\u003e\n\nSamsara 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.\n\nThe Samsara API is a [RESTful API](https://en.wikipedia.org/wiki/Representational_state_transfer). It uses standard [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) authentication, verbs, and response codes, and it returns [JSON](http://www.json.org/) response bodies. If you're familiar with what you can build with a REST API, then this will be your go-to API reference.\n\nIf you have any questions, please visit https://samsara.com/help.\n\n## Endpoints\n\nAll our APIs can be accessed through HTTP requests to URLs like:\n\n```\nhttps://api.samsara.com/v1/\u003cendpoint\u003e\n```\n\n## Authentication\n\nTo authenticate your API request you will need to include your secret token. You can manage your API tokens in the [Dashboard](https://cloud.samsara.com). They are visible under `Settings-\u003eOrganization-\u003eAPI Tokens`.\n\nYour 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.\n\nAuthentication 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:\n\n```curl\nAuthorization: Bearer {access_token}\n```\n\nAll API requests must be made over [HTTPS](https://en.wikipedia.org/wiki/HTTPS). Calls made over plain HTTP or without authentication will fail.\n\n API tokens now have granular scopes. For more on granular scopes and which scopes are required for our legacy APIs, read [here](https://developers.samsara.com/docs/authentication#scopes-for-legacy-api-endpoints). \n\n## Common Patterns\n\nYou can find more info about request methods, response codes, error codes, and versioning [here](https://developers.samsara.com/docs/common-structures).\n",
"title": "Samsara Legacy API",
"version": "2020-06-15"
},
"host": "api.samsara.com",
"paths": {
"/v1/addresses": {
"get": {
"description": "Fetch all addresses/geofences for the organization. An address contains either a circle or polygon geofence describing the address boundaries.",
"tags": [
"Fleet"
],
"summary": "/addresses",
"operationId": "getOrganizationAddresses",
"responses": {
"200": {
"description": "List of addresses/geofences. For each address entry, the geofence field will only be populated with either 'circle' or 'polygon', depending on the geofence type.",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Address"
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"post": {
"description": "Add one or more addresses to the organization",
"tags": [
"Fleet"
],
"summary": "/addresses",
"operationId": "addOrganizationAddresses",
"parameters": [
{
"$ref": "#/parameters/addressAddParam"
}
],
"responses": {
"200": {
"description": "List of added addresses/geofences. For each address entry, the geofence field will only be populated with either 'circle' or 'polygon', depending on the geofence type. Circle geofences added without a specific lat/lng are geocoded asynchronously, and will be 0,0 in the immediate response.",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Address"
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/addresses/{addressId}": {
"get": {
"description": "Fetch an address by its id.",
"tags": [
"Fleet"
],
"summary": "/addresses/{addressId}",
"operationId": "getOrganizationAddress",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the address/geofence",
"name": "addressId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The address/geofence. The geofence field will only be populated with either 'circle' or 'polygon', depending on the geofence type.",
"schema": {
"$ref": "#/definitions/Address"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"delete": {
"description": "Delete an address.",
"tags": [
"Fleet"
],
"summary": "/addresses/{addressId}",
"operationId": "deleteOrganizationAddress",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the address/geofence",
"name": "addressId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Address was successfully deleted. No response body is returned."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"patch": {
"description": "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.",
"tags": [
"Fleet"
],
"summary": "/addresses/{addressId}",
"operationId": "updateOrganizationAddress",
"parameters": [
{
"$ref": "#/parameters/addressUpdateParam"
},
{
"type": "integer",
"format": "int64",
"description": "ID of the address/geofence",
"name": "addressId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Address was successfully updated. No response body is returned."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/contacts": {
"get": {
"description": "Fetch all contacts for the organization.",
"tags": [
"Contacts"
],
"summary": "/contacts",
"operationId": "listContacts",
"responses": {
"200": {
"description": "List of contacts.",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Contact"
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"post": {
"description": "Add a contact to the organization.",
"tags": [
"Contacts"
],
"summary": "/contacts",
"operationId": "addOrganizationContact",
"parameters": [
{
"$ref": "#/parameters/addContactParam"
}
],
"responses": {
"200": {
"description": "Contact was successfully added.",
"schema": {
"$ref": "#/definitions/ContactData"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/contacts/{contact_id}": {
"get": {
"description": "Fetch a contact by its id.",
"tags": [
"Contacts"
],
"summary": "/contacts/{contact_id}",
"operationId": "getOrganizationContact",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the contact. Must contain only digits 0-9.",
"name": "contact_id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The contact.",
"schema": {
"$ref": "#/definitions/Contact"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"delete": {
"description": "Remove a contact from the organization.",
"tags": [
"Contacts"
],
"summary": "/contacts/{contact_id}",
"operationId": "deleteOrganizationContact",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the contact. Must contain only digits 0-9.",
"name": "contact_id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Contact was successfully deleted."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"patch": {
"description": "Update the name, phone number or email of a contact using the contact id. Only fields to be changed need to be supplied.",
"tags": [
"Contacts"
],
"summary": "/contacts/{contact_id}",
"operationId": "updateOrganizationContact",
"parameters": [
{
"$ref": "#/parameters/updateContactParam"
},
{
"type": "integer",
"format": "int64",
"description": "ID of the contact. Must contain only digits 0-9.",
"name": "contact_id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Contact was successfully updated.",
"schema": {
"$ref": "#/definitions/ContactData"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/add_address": {
"post": {
"description": "This method adds an address book entry.",
"tags": [
"Fleet"
],
"summary": "/fleet/add_address",
"operationId": "addFleetAddress",
"parameters": [
{
"name": "addressParam",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"name",
"address",
"radius"
],
"properties": {
"address": {
"description": "The address of the entry to add, as it would be recognized if provided to maps.google.com.",
"type": "string",
"example": "501 York St"
},
"name": {
"description": "Name of the location to add to the address book.",
"type": "string",
"example": "HQ"
},
"radius": {
"description": "Radius in meters of the address (used for matching vehicle trip stops to this location).",
"type": "integer",
"example": 10
}
}
}
}
],
"responses": {
"200": {
"description": "Address was successfully added. No response body is returned."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/assets": {
"get": {
"description": "Fetch all of the assets.",
"tags": [
"Fleet",
"Assets"
],
"summary": "/fleet/assets",
"operationId": "getAllAssets",
"responses": {
"200": {
"description": "List of assets.",
"schema": {
"type": "object",
"properties": {
"assets": {
"type": "array",
"items": {
"$ref": "#/definitions/Asset"
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/assets/locations": {
"get": {
"description": "Fetch current locations of all assets.",
"tags": [
"Fleet",
"Assets"
],
"summary": "/fleet/assets/locations",
"operationId": "getAllAssetCurrentLocations",
"parameters": [
{
"$ref": "#/parameters/paginationStartingAfterParam"
},
{
"$ref": "#/parameters/paginationEndingBeforeParam"
},
{
"$ref": "#/parameters/paginationLimitParam"
},
{
"$ref": "#/parameters/tagIdsPathParam"
}
],
"responses": {
"200": {
"description": "List of assets and their current locations.",
"schema": {
"type": "object",
"properties": {
"assets": {
"type": "array",
"items": {
"$ref": "#/definitions/AssetCurrentLocationsResponse"
}
},
"pagination": {
"$ref": "#/definitions/Pagination"
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/assets/reefers": {
"get": {
"description": "Fetches all reefers and reefer-specific stats.",
"tags": [
"Fleet",
"Assets"
],
"summary": "/fleet/assets/reefers",
"operationId": "getAssetsReefers",
"parameters": [
{
"$ref": "#/parameters/assetHistoryStartTimeParam"
},
{
"$ref": "#/parameters/assetHistoryEndTimeParam"
},
{
"$ref": "#/parameters/paginationStartingAfterParam"
},
{
"$ref": "#/parameters/paginationEndingBeforeParam"
},
{
"$ref": "#/parameters/paginationLimitParam"
}
],
"responses": {
"200": {
"description": "All org reefers and reefer-specific details.",
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/AssetsReefer"
}
},
"pagination": {
"$ref": "#/definitions/Pagination"
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/assets/{asset_id}/locations": {
"get": {
"description": "Fetch the historical locations for the asset.",
"tags": [
"Fleet",
"Assets"
],
"summary": "/fleet/assets/{assetId}/locations",
"operationId": "getAssetLocation",
"parameters": [
{
"$ref": "#/parameters/assetIdParam"
},
{
"$ref": "#/parameters/assetHistoryStartTimeParam"
},
{
"$ref": "#/parameters/assetHistoryEndTimeParam"
}
],
"responses": {
"200": {
"description": "Asset location details.",
"schema": {
"$ref": "#/definitions/AssetLocationResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/assets/{asset_id}/reefer": {
"get": {
"description": "Fetch the reefer-specific stats of an asset.",
"tags": [
"Fleet",
"Assets"
],
"summary": "/fleet/assets/{assetId}/reefer",
"operationId": "getAssetReefer",
"parameters": [
{
"$ref": "#/parameters/assetIdParam"
},
{
"$ref": "#/parameters/assetHistoryStartTimeParam"
},
{
"$ref": "#/parameters/assetHistoryEndTimeParam"
}
],
"responses": {
"200": {
"description": "Reefer-specific asset details.",
"schema": {
"$ref": "#/definitions/AssetReeferResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/dispatch/routes": {
"get": {
"description": "List all routes scheduled within a given time period. Routes are returned if *both* of the following conditions are met:\n\n- The route's `scheduled_start_ms` is *before* the timestamp: `end_time` (defaults to *now*)\n- The route's `scheduled_end_ms` is *after* the timestamp: `end_time - duration` (defaults to *now - 24 hours*)\n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our \u003ca href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\"\u003eAPI feedback form\u003c/a\u003e. If you encountered an issue or noticed inaccuracies in the API documentation, please \u003ca href=\"https://www.samsara.com/help\" target=\"_blank\"\u003esubmit a case\u003c/a\u003e to our support team.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/dispatch/routes",
"operationId": "fetchAllDispatchRoutes",
"parameters": [
{
"$ref": "#/parameters/routeEndTimeParam"
},
{
"$ref": "#/parameters/routeDurationParam"
}
],
"responses": {
"200": {
"description": "All dispatch route objects.",
"schema": {
"$ref": "#/definitions/DispatchRoutes"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"post": {
"description": "Create a new dispatch route.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/dispatch/routes",
"operationId": "createDispatchRoute",
"parameters": [
{
"$ref": "#/parameters/routeCreateParam"
}
],
"responses": {
"200": {
"description": "Created route object including the new route ID.",
"schema": {
"$ref": "#/definitions/DispatchRoute"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/dispatch/routes/job_updates": {
"get": {
"description": "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.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/dispatch/routes/job_updates",
"operationId": "fetchAllRouteJobUpdates",
"parameters": [
{
"$ref": "#/parameters/lastReceivedSequenceIDParam"
},
{
"$ref": "#/parameters/jobUpdatesIncludeParam"
}
],
"responses": {
"200": {
"description": "All job updates on routes.",
"schema": {
"$ref": "#/definitions/allRouteJobUpdates"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/dispatch/routes/{route_id_or_external_id}": {
"get": {
"description": "Fetch a dispatch route by id.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/dispatch/routes/{route_id}",
"operationId": "getDispatchRouteById",
"responses": {
"200": {
"description": "The dispatch route corresponding to route_id.",
"schema": {
"$ref": "#/definitions/DispatchRoute"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"put": {
"description": "Update the dispatch route. Examples of this include:\n- 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.\n- Updating the assigned driver or vehicle. (Routes may be assigned to a driver or a vehicle, but not both).\n- Updating the location and/or timing information of the route.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/dispatch/routes/{route_id}/",
"operationId": "updateDispatchRouteById",
"parameters": [
{
"$ref": "#/parameters/routeUpdateParam"
}
],
"responses": {
"200": {
"description": "The updated route corresponding to route_id.",
"schema": {
"$ref": "#/definitions/DispatchRoute"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"delete": {
"description": "Delete a dispatch route and its associated jobs.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/dispatch/routes/{route_id}/",
"operationId": "deleteDispatchRouteById",
"parameters": [
{
"$ref": "#/parameters/applyToFutureRoutesParam"
}
],
"responses": {
"200": {
"description": "Successfully deleted the dispatch route. No response body is returned."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"$ref": "#/parameters/routeIdOrExternalIdParam"
}
]
},
"/v1/fleet/dispatch/routes/{route_id_or_external_id}/history": {
"get": {
"description": "Fetch the history of a dispatch route.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/dispatch/routes/{route_id}/history",
"operationId": "getDispatchRouteHistory",
"parameters": [
{
"$ref": "#/parameters/routeHistoryStartTimeParam"
},
{
"$ref": "#/parameters/routeHistoryEndTimeParam"
},
{
"$ref": "#/parameters/routeIdOrExternalIdParam"
}
],
"responses": {
"200": {
"description": "The historical route state changes between start_time and end_time.",
"schema": {
"$ref": "#/definitions/DispatchRouteHistory"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/drivers": {
"get": {
"description": "Get all *active* drivers. When drivers leave an organization, you can deactivate them. Use [DELETE /v1/fleet/drivers/{id}](#operation/deactivateDriver) to deactivate drivers and [GET /v1/fleet/drivers/inactive](#operation/getAllDeactivatedDrivers) to get inactive drivers. Inactive driver records will still be part of reports such as Hours of Service.",
"tags": [
"Fleet"
],
"summary": "/fleet/drivers",
"operationId": "getFleetDrivers",
"responses": {
"200": {
"description": "All active drivers.",
"schema": {
"$ref": "#/definitions/DriversResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/drivers/create": {
"post": {
"description": "Create a new driver.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Drivers"
],
"summary": "/fleet/drivers/create",
"operationId": "createDriver",
"parameters": [
{
"$ref": "#/parameters/createDriverParam"
}
],
"responses": {
"200": {
"description": "Returns the successfully created the driver.",
"schema": {
"$ref": "#/definitions/Driver"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/drivers/document_types": {
"get": {
"description": "Fetch all of the document types.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet"
],
"summary": "/fleet/drivers/document_types",
"operationId": "getDriverDocumentTypesByOrgId",
"responses": {
"200": {
"description": "Returns all of the document types.",
"schema": {
"$ref": "#/definitions/DocumentTypes"
},
"examples": {
"application/json": {
"conditionalFieldSections": [
{
"conditionalFieldFirstIndex": 1,
"conditionalFieldLastIndex": 1,
"triggeringFieldIndex": 0,
"triggeringFieldValue": "Yes"
}
],
"fieldTypes": [
{
"label": "Was there damage?",
"multipleChoiceValueTypeMetadata": {
"multipleChoiceOptionLabels": [
{
"label": "Yes"
},
{
"label": "No"
}
]
},
"valueType": "ValueType_MultipleChoice"
},
{
"label": "Damage Photos",
"valueType": "ValueType_Photo"
},
{
"label": "Date",
"valueType": "ValueType_DateTime"
}
],
"name": "Damage Report",
"orgId": 123,
"uuid": "4aff772c-a7bb-45e6-8e41-6a53e34feb83"
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/drivers/documents": {
"get": {
"description": "Fetch all of the documents.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet"
],
"summary": "/fleet/drivers/documents",
"operationId": "getDriverDocumentsByOrgId",
"parameters": [
{
"$ref": "#/parameters/documentsEndMsParam"
},
{
"$ref": "#/parameters/documentsDurationMsParam"
},
{
"$ref": "#/parameters/documentQueryByParam"
}
],
"responses": {
"200": {
"description": "Returns all of the documents.",
"schema": {
"$ref": "#/definitions/Documents"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/drivers/inactive": {
"get": {
"description": "Get all *inactive* drivers. When drivers leave an organization, you can deactivate them. You can use [DELETE /v1/fleet/drivers/{id}](#operation/deactivateDriver) to deactivate drivers. Inactive driver records will still be part of reports such as Hours of Service.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Drivers"
],
"summary": "/fleet/drivers/inactive",
"operationId": "getAllDeactivatedDrivers",
"responses": {
"200": {
"description": "All inactive drivers.",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Driver"
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/drivers/inactive/{driver_id_or_external_id}": {
"get": {
"description": "Get an *inactive* driver. When drivers leave an organization, you can deactivate them. You can use [DELETE /v1/fleet/drivers/{id}](#operation/deactivateDriver) to deactivate drivers. You can use [PUT /v1/fleet/drivers/{id}](#operation/reactivateDriverById) to reactivate drivers. Inactive driver records will still be part of reports such as Hours of Service.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Drivers"
],
"summary": "/fleet/drivers/inactive/{driver_id or external_id}",
"operationId": "getDeactivatedDriverById",
"responses": {
"200": {
"description": "The inactive driver.",
"schema": {
"$ref": "#/definitions/Driver"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"put": {
"description": "Reactivate a driver.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Drivers"
],
"summary": "/fleet/drivers/inactive/{driver_id or external_id}",
"operationId": "reactivateDriverById",
"parameters": [
{
"$ref": "#/parameters/reactivateDriverParam"
}
],
"responses": {
"200": {
"description": "The reactivated driver, which is now available at [GET /v1/fleet/drivers/{id}](#operation/getDriverById).",
"schema": {
"$ref": "#/definitions/CurrentDriver"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"$ref": "#/parameters/driverIdOrExternalIdParam"
}
]
},
"/v1/fleet/drivers/summary": {
"post": {
"description": "Get the distance and time each driver in an organization has driven in a given time period.\n\n**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.",
"tags": [
"Fleet"
],
"summary": "/fleet/drivers/summary",
"operationId": "getFleetDriversSummary",
"parameters": [
{
"type": "boolean",
"description": "Snap query result to HOS day boundaries.",
"name": "snap_to_day_bounds",
"in": "query"
},
{
"name": "driversSummaryParam",
"in": "body",
"schema": {
"type": "object",
"required": [
"orgId",
"startMs",
"endMs"
],
"properties": {
"endMs": {
"description": "End time (ms) of queried time period. Must be greater than startMs.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"orgId": {
"description": "Organization ID that the drivers belong to",
"type": "integer",
"format": "int64",
"example": 555
},
"startMs": {
"description": "Start time (ms) of queried time period.",
"type": "integer",
"format": "int64",
"example": 1462878398034
}
}
}
}
],
"responses": {
"200": {
"description": "Distance traveled and time active for each driver in the organization over the specified time period.",
"schema": {
"$ref": "#/definitions/DriversSummaryResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/drivers/{driverId}/safety/score": {
"get": {
"description": "Fetch the safety score for the driver.",
"tags": [
"Fleet",
"Safety"
],
"summary": "/fleet/drivers/{driverId}/safety/score",
"operationId": "getDriverSafetyScore",
"parameters": [
{
"$ref": "#/parameters/safetyScoreStartMsParam"
},
{
"$ref": "#/parameters/safetyScoreEndMsParam"
}
],
"responses": {
"200": {
"description": "Safety score details.",
"schema": {
"$ref": "#/definitions/DriverSafetyScoreResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the driver. Must contain only digits 0-9.",
"name": "driverId",
"in": "path",
"required": true
}
]
},
"/v1/fleet/drivers/{driver_id_or_external_id}": {
"get": {
"description": "Get an *active* driver. When drivers leave an organization, you can deactivate them. Use [GET /v1/fleet/drivers/inactive/{id}](#operation/getDeactivatedDriverById) to get an inactive driver, and use [DELETE /v1/fleet/drivers/{id}](#operation/deactivateDriver) to deactivate drivers.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Drivers"
],
"summary": "/fleet/drivers/{driver_id or external_id}",
"operationId": "getDriverById",
"responses": {
"200": {
"description": "The driver with the given ID.",
"schema": {
"$ref": "#/definitions/CurrentDriver"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"delete": {
"description": "Deactivate a driver. You can use [PUT /v1/fleet/drivers/{id}](#operation/reactivateDriverById) to reactivate a driver.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Drivers"
],
"summary": "/fleet/drivers/{driver_id or external_id}",
"operationId": "deactivateDriver",
"responses": {
"200": {
"description": "Successfully deactivated the driver, which is now referenced by [GET /v1/fleet/drivers/inactive/{id}](#operation/getDeactivatedDriverById)."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"patch": {
"description": "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}](#operation/deactivateDriver) to deactivate drivers, and [PUT /v1/fleet/drivers/{id}](#operation/reactivateDriverById) to reactivate drivers.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Drivers"
],
"summary": "/fleet/drivers/{driver_id or external_id}",
"operationId": "updateDriverById",
"parameters": [
{
"$ref": "#/parameters/updateDriverParam"
}
],
"responses": {
"200": {
"description": "The updated driver.",
"schema": {
"$ref": "#/definitions/CurrentDriver"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"$ref": "#/parameters/driverIdOrExternalIdParam"
}
]
},
"/v1/fleet/drivers/{driver_id}/dispatch/routes": {
"get": {
"description": "List all routes scheduled within a given time period for the given driver. Routes are returned if *both* of the following conditions are met:\n\n- The route's `scheduled_start_ms` is *before* the timestamp: `end_time` (defaults to *now*)\n- The route's `scheduled_end_ms` is *after* the timestamp: `end_time - duration` (defaults to *now - 24 hours*)\n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our \u003ca href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\"\u003eAPI feedback form\u003c/a\u003e. If you encountered an issue or noticed inaccuracies in the API documentation, please \u003ca href=\"https://www.samsara.com/help\" target=\"_blank\"\u003esubmit a case\u003c/a\u003e to our support team.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/drivers/{driver_id}/dispatch/routes",
"operationId": "getDispatchRoutesByDriverId",
"parameters": [
{
"$ref": "#/parameters/routeEndTimeParam"
},
{
"$ref": "#/parameters/routeDurationParam"
}
],
"responses": {
"200": {
"description": "Returns the dispatch routes for the given driver_id.",
"schema": {
"$ref": "#/definitions/DispatchRoutes"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"post": {
"description": "Create a new dispatch route for the driver with driver_id.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/drivers/{driver_id}/dispatch/routes",
"operationId": "createDriverDispatchRoute",
"parameters": [
{
"$ref": "#/parameters/routeCreateParam"
}
],
"responses": {
"200": {
"description": "Created route object including the new route ID.",
"schema": {
"$ref": "#/definitions/DispatchRoute"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the driver with the associated routes. Must contain only digits 0-9.",
"name": "driver_id",
"in": "path",
"required": true
}
]
},
"/v1/fleet/drivers/{driver_id}/documents": {
"post": {
"description": "Create a driver document for the given driver.\n\nYou can create a document in one of two states: \"Required\" or \"Submitted\":\n\n- Setting the document state to \"Submitted\" will submit the document on behalf of the driver.\n\n- Setting the document state to \"Required\" will create a pre-populated document for the driver to fill out in the Driver App.\n\n**Populating document fields**\n\nYou 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](#operation/getDriverDocumentTypesByOrgId) endpoint.\n\nYou 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.\n\n\n\n**Setting document fields to default values**\n\nIf 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:\n\n```\n\n{\n\n \"documentTypeUuid\": \"79008acc-56d6-49f4-b5d2-4101ce4b497c\",\n\n \"fields\": [\n\n {\n\n \"label\": \"Number Field\",\n\n \"valueType\": \"ValueType_Number\",\n\n \"numberValue\": null\n\n },\n\n {\n\n \"label\": \"Signature Field\",\n\n \"valueType\": \"ValueType_Signature\"\n\n }\n\n ],\n\n \"dispatchJobId\": 4333299083,\n\n \"state\":\"Required\"\n\n}\n\n```\n\nIn 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.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet"
],
"summary": "/fleet/drivers/{driver_id}/documents",
"operationId": "createDriverDocument",
"parameters": [
{
"$ref": "#/parameters/documentCreateParam"
}
],
"responses": {
"200": {
"description": "Returns the created document.",
"schema": {
"$ref": "#/definitions/Document"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the driver for whom the document is created. Must contain only digits 0-9.",
"name": "driver_id",
"in": "path",
"required": true
}
]
},
"/v1/fleet/drivers/{driver_id}/documents/{document_id}": {
"get": {
"description": "Fetches a single document submission by driver.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet"
],
"summary": "/fleet/drivers/{driver_id}/documents/{document_id}",
"operationId": "getDriverDocumentByIdAndDriverId",
"responses": {
"200": {
"description": "Returns the specified document.",
"schema": {
"$ref": "#/definitions/Document"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"delete": {
"description": "Deletes a single document submission by driver.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet"
],
"summary": "/fleet/drivers/{driver_id}/documents/{document_id}",
"operationId": "deleteDriverDocumentByIdAndDriverId",
"responses": {
"200": {
"description": "Deletes the specified document."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the driver who submitted the document. Must contain only digits 0-9.",
"name": "driver_id",
"in": "path",
"required": true
},
{
"type": "string",
"description": "ID of document.",
"name": "document_id",
"in": "path",
"required": true
}
]
},
"/v1/fleet/drivers/{driver_id}/hos/duty_status": {
"post": {
"description": "Set an individual driver’s current duty status to 'On Duty' or 'Off Duty'.\n\n 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.",
"tags": [
"Fleet"
],
"summary": "Set a duty status for a specific driver",
"operationId": "setCurrentDutyStatus",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the driver for whom the duty status is being set.",
"name": "driver_id",
"in": "path",
"required": true
},
{
"name": "dutyStatusParams",
"in": "body",
"schema": {
"type": "object",
"required": [
"duty_status"
],
"properties": {
"duty_status": {
"description": "Duty status to set the driver to. The only supported values are 'ON_DUTY' and 'OFF_DUTY'.",
"type": "string",
"example": "ON_DUTY"
},
"location": {
"description": "Location to associate the duty status change with.",
"type": "string",
"example": "Loading dock"
},
"remarks": {
"description": "Remark to associate the duty status change with.",
"type": "string",
"example": "Beginning On Duty Shift"
},
"status_change_at_ms": {
"description": "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.",
"type": "number",
"format": "int64",
"example": 1580834793568
},
"vehicle_id": {
"description": "Vehicle ID to associate the duty status change with.",
"type": "number",
"format": "int64",
"example": 1234
}
}
}
}
],
"responses": {
"200": {
"description": "Successfully changed duty status. No response body is returned."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/drivers/{driver_id}/hos_daily_logs": {
"get": {
"description": "Get summarized daily Hours of Service charts for a specified driver.\n\nThe 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.\n\nThe 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.\n\nThe `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:\n\nLet's say a `driver`'s `eldDayStartHour` is `0` and their timezone is `America/Chicago`.\n\nIf `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].\n\n**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.",
"tags": [
"Fleet"
],
"summary": "/fleet/drivers/{driver_id}/hos_daily_logs",
"operationId": "getFleetDriversHosDailyLogs",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the driver with HOS logs.",
"name": "driver_id",
"in": "path",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "Beginning of the time range, specified in milliseconds UNIX time.",
"name": "startMs",
"in": "query",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "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).",
"name": "endMs",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "Distance traveled and time active for each driver in the organization over the specified time period.",
"schema": {
"$ref": "#/definitions/DriverDailyLogResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/hos_authentication_logs": {
"get": {
"description": "Get the HOS (hours of service) signin and signout logs for the specified driver. The response includes 4 fields that are now deprecated.\n\n**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.",
"tags": [
"Fleet"
],
"summary": "/fleet/hos_authentication_logs",
"operationId": "getFleetHosAuthenticationLogs",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "Driver ID to query.",
"name": "driverId",
"in": "query",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "Beginning of the time range, specified in milliseconds UNIX time.",
"name": "startMs",
"in": "query",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "End of the time range, specified in milliseconds UNIX time.",
"name": "endMs",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "HOS authentication logs for the specified driver.",
"schema": {
"$ref": "#/definitions/HosAuthenticationLogsResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/hos_logs": {
"post": {
"description": "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.\n\n**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.",
"tags": [
"Fleet"
],
"summary": "/fleet/hos_logs",
"operationId": "getFleetHosLogs",
"parameters": [
{
"name": "hosLogsParam",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"driverId",
"startMs",
"endMs"
],
"properties": {
"driverId": {
"description": "Driver ID to query.",
"type": "integer",
"format": "int64",
"example": 444
},
"endMs": {
"description": "End of the time range, specified in milliseconds UNIX time.",
"type": "integer",
"example": 1462881998034
},
"startMs": {
"description": "Beginning of the time range, specified in milliseconds UNIX time.",
"type": "integer",
"example": 1462878398034
}
}
}
}
],
"responses": {
"200": {
"description": "HOS logs for the specified driver.",
"schema": {
"$ref": "#/definitions/HosLogsResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/hos_logs_summary": {
"get": {
"description": "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](https://kb.samsara.com/hc/en-us/articles/360026132972-Upgrading-API-Tokens).\n\n**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.",
"tags": [
"Fleet"
],
"summary": "/fleet/hos_logs_summary",
"operationId": "getFleetHosLogsSummary",
"parameters": [
{
"type": "string",
"description": "Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter.",
"name": "after",
"in": "query"
},
{
"type": "number",
"format": "int64",
"description": "Pagination parameter indicating the number of results to return in this request. Used in conjunction with 'after'.",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "HOS logs for the specified driver.",
"schema": {
"$ref": "#/definitions/HosLogsSummaryResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/list": {
"get": {
"description": "Get list of the vehicles. This method returns a list of the vehicles in the Samsara Cloud and information about them.",
"tags": [
"Fleet"
],
"summary": "/fleet/list",
"operationId": "listFleet",
"parameters": [
{
"$ref": "#/parameters/paginationStartingAfterParam"
},
{
"$ref": "#/parameters/paginationEndingBeforeParam"
},
{
"$ref": "#/parameters/paginationLimitParam"
}
],
"responses": {
"200": {
"description": "List of vehicles and information about each.",
"schema": {
"type": "object",
"properties": {
"groupId": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 101
},
"pagination": {
"$ref": "#/definitions/Pagination"
},
"vehicles": {
"type": "array",
"items": {
"$ref": "#/definitions/Vehicle"
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/locations": {
"get": {
"description": "Get current location of vehicles.",
"tags": [
"Fleet"
],
"summary": "/fleet/locations",
"operationId": "getFleetLocations",
"parameters": [
{
"type": "string",
"description": "Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter.",
"name": "after",
"in": "query"
},
{
"maximum": 512,
"minimum": 1,
"type": "number",
"format": "int64",
"default": 512,
"description": "Pagination parameter indicating the number of results to return in this request. Used in conjunction with 'after'.",
"name": "limit",
"in": "query"
},
{
"type": "array",
"items": {
"type": "string"
},
"description": "A comma-separated list of vehicle IDs. Example: `vehicleIds=1000,1001`",
"name": "vehicleIds",
"in": "query"
},
{
"$ref": "#/parameters/tagIdsPathParam"
}
],
"responses": {
"200": {
"description": "List of vehicle objects containing their location and the time at which that location was logged.",
"schema": {
"type": "object",
"properties": {
"pagination": {
"type": "object",
"required": [
"hasNextPage",
"endCursor"
],
"properties": {
"endCursor": {
"description": "Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter. This may be an empty string if there are no more pages left to view.",
"type": "string",
"example": "MTA1MDc5MB=="
},
"hasNextPage": {
"description": "True if there are more pages of results after this response.",
"type": "boolean"
}
}
},
"vehicles": {
"type": "array",
"items": {
"$ref": "#/definitions/VehicleLocation"
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/maintenance/dvirs": {
"get": {
"description": "Get DVIRs for the org within provided time constraints",
"tags": [
"Fleet"
],
"summary": "/fleet/maintenance/dvirs",
"operationId": "getDvirs",
"parameters": [
{
"type": "integer",
"description": "Time in millis until the last dvir log.",
"name": "end_ms",
"in": "query",
"required": true
},
{
"maximum": 7776000000,
"type": "integer",
"description": "Time in millis which corresponds to the duration before the end_ms. Must be less than or equal to 90 days.",
"name": "duration_ms",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "DVIRs for the specified duration.",
"schema": {
"$ref": "#/definitions/DvirListResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"post": {
"description": "Create a new dvir, marking a vehicle or trailer safe or unsafe.",
"tags": [
"Fleet"
],
"summary": "/fleet/maintenance/dvirs",
"operationId": "createDvir",
"parameters": [
{
"$ref": "#/parameters/createDvirParam"
}
],
"responses": {
"200": {
"description": "Newly created DVIR.",
"schema": {
"$ref": "#/definitions/DvirBase"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/maintenance/list": {
"get": {
"description": "Get list of the vehicles with any engine faults or check light data.\n\n**We suggest you use our updated and more flexible [vehicle/stats endpoints](https://developers.samsara.com/docs/vehicle-stats) for fetching vehicle fault codes.**",
"tags": [
"Fleet"
],
"summary": "/fleet/maintenance/list",
"operationId": "getFleetMaintenanceList",
"responses": {
"200": {
"description": "List of vehicles and maintenance information about each.",
"schema": {
"type": "object",
"properties": {
"vehicles": {
"type": "array",
"items": {
"$ref": "#/definitions/VehicleMaintenance"
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/messages": {
"get": {
"description": "Get all messages.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Messages"
],
"summary": "/fleet/messages",
"operationId": "getMessages",
"parameters": [
{
"$ref": "#/parameters/getMessagesEndMsParam"
},
{
"$ref": "#/parameters/getMessagesDurationMsParam"
}
],
"responses": {
"200": {
"description": "Returns the fetched messages from most recently sent to least recently sent.",
"schema": {
"description": "A list of messages.",
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/MessagesResponse"
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"post": {
"description": "Send a message to a list of driver ids.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Messages"
],
"summary": "/fleet/messages",
"operationId": "createMessages",
"parameters": [
{
"$ref": "#/parameters/createMessagesParam"
}
],
"responses": {
"200": {
"description": "Returns the created messages.",
"schema": {
"description": "A list of created messages.",
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/Messages"
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/set_data": {
"post": {
"description": "This API allows you to update metadata for a single vehicle.",
"tags": [
"Fleet"
],
"summary": "/fleet/set_data",
"operationId": "updateVehicles",
"parameters": [
{
"name": "vehicleUpdateParam",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"vehicles"
],
"properties": {
"vehicles": {
"type": "array",
"items": {
"description": "A vehicle object.",
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/definitions/Vehicle/properties/id"
},
"name": {
"$ref": "#/definitions/Vehicle/properties/name"
},
"note": {
"$ref": "#/definitions/Vehicle/properties/note"
}
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "Vehicles were successfully updated. No response body is returned."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/trailers/assignments": {
"get": {
"description": "Fetch trailer assignment data for all trailers in your organization.",
"tags": [
"Fleet"
],
"summary": "/fleet/trailers/assignments",
"operationId": "getAllTrailerAssignments",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "Timestamp in Unix epoch miliseconds representing the start of the period to fetch. Omitting both startMs and endMs only returns current assignments.",
"name": "startMs",
"in": "query"
},
{
"type": "integer",
"format": "int64",
"description": "Timestamp in Unix epoch miliseconds representing the end of the period to fetch. Omitting endMs sets endMs as the current time",
"name": "endMs",
"in": "query"
},
{
"$ref": "#/parameters/paginationLimitParam"
},
{
"$ref": "#/parameters/paginationStartingAfterParam"
},
{
"$ref": "#/parameters/paginationEndingBeforeParam"
}
],
"responses": {
"200": {
"description": "Returns trailer assignment data for all trailers in your organization",
"schema": {
"type": "object",
"properties": {
"pagination": {
"$ref": "#/definitions/Pagination"
},
"trailers": {
"type": "array",
"items": {
"$ref": "#/definitions/TrailerAssignmentsResponse"
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/trailers/{trailerId}/assignments": {
"get": {
"description": "Fetch trailer assignment data for a single trailer.",
"tags": [
"Fleet"
],
"summary": "/fleet/trailers/{trailerId}/assignments",
"operationId": "getFleetTrailerAssignments",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of trailer. Must contain only digits 0-9.",
"name": "trailerId",
"in": "path",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "Timestamp in Unix epoch milliseconds representing the start of the period to fetch. Omitting both startMs and endMs only returns current assignments.",
"name": "startMs",
"in": "query"
},
{
"type": "integer",
"format": "int64",
"description": "Timestamp in Unix epoch milliseconds representing the end of the period to fetch. Omitting endMs sets endMs as the current time",
"name": "endMs",
"in": "query"
}
],
"responses": {
"200": {
"description": "Returns trailer assignment data for a single trailer",
"schema": {
"$ref": "#/definitions/TrailerAssignmentsResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/trips": {
"get": {
"description": "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.",
"tags": [
"Fleet"
],
"summary": "/fleet/trips",
"operationId": "getFleetTrips",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "Vehicle ID to query.",
"name": "vehicleId",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Beginning of the time range, specified in milliseconds UNIX time. Limited to a 90 day window with respect to startMs and endMs",
"name": "startMs",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "End of the time range, specified in milliseconds UNIX time.",
"name": "endMs",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "List of trips taken by the requested vehicle within the specified timeframe. Ongoing trips will be returned with 9223372036854775807 as their endMs.",
"schema": {
"$ref": "#/definitions/TripResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/vehicles/locations": {
"get": {
"description": "Fetch locations for all vehicles between a start/end time. The maximum query duration is 30 minutes (1800000 ms).",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet"
],
"summary": "/fleet/vehicles/locations",
"operationId": "getVehiclesLocations",
"responses": {
"200": {
"description": "Returns locations for all vehicles between a start/end time, with a maximum query duration of 30 minutes (1800000 ms).",
"schema": {
"$ref": "#/definitions/FleetVehiclesLocations"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"type": "integer",
"description": "Time in Unix epoch milliseconds for the start of the query (cannot exceed 30 minutes)",
"name": "startMs",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Time in Unix epoch milliseconds for the end of the query (cannot exceed 30 minutes)",
"name": "endMs",
"in": "query",
"required": true
}
]
},
"/v1/fleet/vehicles/stats": {
"get": {
"description": "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.",
"tags": [
"Fleet"
],
"summary": "/fleet/vehicles/stats",
"operationId": "getVehicleStats",
"parameters": [
{
"type": "integer",
"description": "Time in Unix epoch milliseconds for the start of the query.",
"name": "startMs",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Time in Unix epoch milliseconds for the end of the query.",
"name": "endMs",
"in": "query",
"required": true
},
{
"enum": [
"engineState",
"auxInput1",
"auxInput2"
],
"type": "string",
"description": "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",
"name": "series",
"in": "query"
},
{
"type": "string",
"description": "Comma-separated list of tag ids. Example: tagIds=1,2,3",
"name": "tagIds",
"in": "query"
},
{
"$ref": "#/parameters/paginationStartingAfterParam"
},
{
"$ref": "#/parameters/paginationEndingBeforeParam"
},
{
"$ref": "#/parameters/paginationLimitParam"
}
],
"responses": {
"200": {
"description": "Returns engine state and/or aux input data for all vehicles between a start/end time.",
"schema": {
"type": "object",
"required": [
"vehicleStats"
],
"properties": {
"pagination": {
"$ref": "#/definitions/Pagination"
},
"vehicleStats": {
"type": "array",
"items": {
"type": "object",
"required": [
"vehicleId"
],
"properties": {
"auxInput1": {
"$ref": "#/definitions/AuxInputSeries"
},
"auxInput2": {
"$ref": "#/definitions/AuxInputSeries"
},
"engineState": {
"type": "array",
"items": {
"$ref": "#/definitions/EngineState"
}
},
"externalIds": {
"$ref": "#/definitions/ExternalIDs"
},
"vehicleId": {
"description": "ID of the vehicle.",
"type": "integer",
"format": "int64",
"example": 112
}
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/vehicles/{vehicleId}/safety/harsh_event": {
"get": {
"description": "Fetch harsh event details for a vehicle.",
"tags": [
"Fleet",
"Safety"
],
"summary": "/fleet/vehicles/{vehicleId}/safety/harsh_event",
"operationId": "getVehicleHarshEvent",
"parameters": [
{
"$ref": "#/parameters/harshEventMsParam"
}
],
"responses": {
"200": {
"description": "Harsh event details.",
"schema": {
"$ref": "#/definitions/VehicleHarshEventResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the vehicle. Must contain only digits 0-9.",
"name": "vehicleId",
"in": "path",
"required": true
}
]
},
"/v1/fleet/vehicles/{vehicleId}/safety/score": {
"get": {
"description": "Fetch the safety score for the vehicle.",
"tags": [
"Fleet",
"Safety"
],
"summary": "/fleet/vehicles/{vehicleId}/safety/score",
"operationId": "getVehicleSafetyScore",
"parameters": [
{
"$ref": "#/parameters/safetyScoreStartMsParam"
},
{
"$ref": "#/parameters/safetyScoreEndMsParam"
}
],
"responses": {
"200": {
"description": "Safety score details.",
"schema": {
"$ref": "#/definitions/VehicleSafetyScoreResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the vehicle. Must contain only digits 0-9.",
"name": "vehicleId",
"in": "path",
"required": true
}
]
},
"/v1/fleet/vehicles/{vehicle_id_or_external_id}": {
"get": {
"description": "Gets a specific vehicle.",
"consumes": [
"application/json"
],
"tags": [
"Fleet"
],
"summary": "/fleet/vehicles/{vehicle_id or external_id}",
"operationId": "getFleetVehicle",
"parameters": [
{
"$ref": "#/parameters/vehicleIdOrExternalIdParam"
}
],
"responses": {
"200": {
"description": "The specified vehicle.",
"schema": {
"$ref": "#/definitions/FleetVehicleResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"patch": {
"description": "Updates the specified vehicle using JSON merge patch format. See IETF RFC 7396: https://tools.ietf.org/html/rfc7396.",
"consumes": [
"application/json",
"application/merge-patch+json"
],
"tags": [
"Fleet"
],
"summary": "/fleet/vehicles/{vehicle_id or external_id}",
"operationId": "patchFleetVehicle",
"parameters": [
{
"$ref": "#/parameters/vehicleIdOrExternalIdParam"
},
{
"name": "data",
"in": "body",
"required": true,
"schema": {
"type": "object",
"properties": {
"externalIds": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"example": {
"maintenanceId": "ABFS18600"
}
},
"harsh_accel_setting": {
"description": "Harsh Event Detection Setting\n* 0: Passenger\n* 1: Light Truck\n* 2: Heavy\n* 3: Off\n* 4: Automatic",
"type": "integer",
"format": "string",
"enum": [
"Passenger",
"Light Truck",
"Heavy",
"Off",
"Auto"
]
},
"name": {
"description": "Name",
"type": "string"
}
}
}
}
],
"responses": {
"200": {
"description": "The updated vehicle.",
"schema": {
"$ref": "#/definitions/FleetVehicleResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/fleet/vehicles/{vehicle_id}/dispatch/routes": {
"get": {
"description": "List all routes scheduled within a given time period for the given vehicle. Routes are returned if *both* of the following conditions are met:\n\n- The route's `scheduled_start_ms` is *before* the timestamp: `end_time` (defaults to *now*)\n- The route's `scheduled_end_ms` is *after* the timestamp: `end_time - duration` (defaults to *now - 24 hours*)\n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our \u003ca href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\"\u003eAPI feedback form\u003c/a\u003e. If you encountered an issue or noticed inaccuracies in the API documentation, please \u003ca href=\"https://www.samsara.com/help\" target=\"_blank\"\u003esubmit a case\u003c/a\u003e to our support team.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/vehicles/{vehicle_id}/dispatch/routes",
"operationId": "getDispatchRoutesByVehicleId",
"parameters": [
{
"$ref": "#/parameters/routeEndTimeParam"
},
{
"$ref": "#/parameters/routeDurationParam"
}
],
"responses": {
"200": {
"description": "Returns all of the dispatch routes for the given vehicle_id.",
"schema": {
"$ref": "#/definitions/DispatchRoutes"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"post": {
"description": "Create a new dispatch route for the vehicle with vehicle_id.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet",
"Routes"
],
"summary": "/fleet/vehicles/{vehicle_id}/dispatch/routes",
"operationId": "createVehicleDispatchRoute",
"parameters": [
{
"$ref": "#/parameters/routeCreateParam"
}
],
"responses": {
"200": {
"description": "Created route object including the new route ID.",
"schema": {
"$ref": "#/definitions/DispatchRoute"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the vehicle with the associated routes. Must contain only digits 0-9.",
"name": "vehicle_id",
"in": "path",
"required": true
}
]
},
"/v1/fleet/vehicles/{vehicle_id}/locations": {
"get": {
"description": "Fetch locations for a given vehicle between a start/end time. The maximum query duration is one hour.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Fleet"
],
"summary": "/fleet/vehicles/{vehicle_id}/locations",
"operationId": "getVehicleLocations",
"responses": {
"200": {
"description": "Returns locations for a given vehicle between a start/end time, with a maximum query duration of one hour.",
"schema": {
"$ref": "#/definitions/FleetVehicleLocations"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the vehicle with the associated routes. Must contain only digits 0-9.",
"name": "vehicle_id",
"in": "path",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "Time in Unix epoch milliseconds for the start of the query (cannot exceed 1 hour)",
"name": "startMs",
"in": "query",
"required": true
},
{
"type": "integer",
"format": "int64",
"description": "Time in Unix epoch milliseconds for the end of the query (cannot exceed 1 hour)",
"name": "endMs",
"in": "query",
"required": true
}
]
},
"/v1/industrial/data": {
"get": {
"description": "Fetch all of the data inputs.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Industrial"
],
"summary": "/industrial/data",
"operationId": "getAllDataInputs",
"parameters": [
{
"$ref": "#/parameters/dataInputStartTimeParam"
},
{
"$ref": "#/parameters/dataInputEndTimeParam"
}
],
"responses": {
"200": {
"description": "List of data inputs.",
"schema": {
"type": "object",
"properties": {
"dataInputs": {
"type": "array",
"items": {
"$ref": "#/definitions/DataInputHistoryResponse"
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/industrial/data/{data_input_id}": {
"get": {
"description": "Fetch datapoints from a given data input.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Industrial"
],
"summary": "/industrial/data/{data_input_id}",
"operationId": "getDataInput",
"parameters": [
{
"$ref": "#/parameters/dataInputIdParam"
},
{
"$ref": "#/parameters/dataInputStartTimeParam"
},
{
"$ref": "#/parameters/dataInputEndTimeParam"
}
],
"responses": {
"200": {
"description": "Returns datapoints for the given data input",
"schema": {
"$ref": "#/definitions/DataInputHistoryResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/industrial/vision/cameras": {
"get": {
"description": "Fetch all cameras.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Industrial"
],
"summary": "/industrial/vision/cameras",
"operationId": "getCameras",
"responses": {
"200": {
"description": "Returns details about a camera.",
"schema": {
"$ref": "#/definitions/VisionCamerasResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/industrial/vision/cameras/{camera_id}/programs": {
"get": {
"description": "Fetch configured programs on the camera.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Industrial"
],
"summary": "/industrial/vision/cameras/{camera_id}/programs",
"operationId": "getVisionProgramsByCamera",
"parameters": [
{
"$ref": "#/parameters/visionCameraIdParam"
}
],
"responses": {
"200": {
"description": "Returns programs configured on the camera.",
"schema": {
"$ref": "#/definitions/ProgramsForTheCameraResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/industrial/vision/run/camera/{camera_id}": {
"get": {
"description": "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.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Industrial"
],
"summary": "/industrial/vision/run/camera/{camera_id}",
"operationId": "getVisionLatestRunCamera",
"parameters": [
{
"$ref": "#/parameters/visionCameraIdParam"
},
{
"$ref": "#/parameters/visionProgramIdParam"
},
{
"$ref": "#/parameters/visionStartAtMsParam"
},
{
"$ref": "#/parameters/visionIncludeParam"
},
{
"$ref": "#/parameters/visionLimitParam"
}
],
"responses": {
"200": {
"description": "Returns the details for this run.",
"schema": {
"$ref": "#/definitions/VisionRunByCameraResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/industrial/vision/runs": {
"get": {
"description": "Fetch runs.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Industrial"
],
"summary": "/industrial/vision/runs",
"operationId": "getVisionRuns",
"parameters": [
{
"$ref": "#/parameters/visionDurationMsParam"
},
{
"$ref": "#/parameters/visionEndMsParam"
}
],
"responses": {
"200": {
"description": "Return runs.",
"schema": {
"$ref": "#/definitions/VisionRunsResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/industrial/vision/runs/{camera_id}": {
"get": {
"description": "Fetch runs by camera.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Industrial"
],
"summary": "/industrial/vision/runs/{camera_id}",
"operationId": "getVisionRunsByCamera",
"parameters": [
{
"$ref": "#/parameters/visionCameraIdParam"
},
{
"$ref": "#/parameters/visionDurationMsParam"
},
{
"$ref": "#/parameters/visionEndMsParam"
}
],
"responses": {
"200": {
"description": "Return runs by cameraId.",
"schema": {
"$ref": "#/definitions/VisionRunsByCameraResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/industrial/vision/runs/{camera_id}/{program_id}/{started_at_ms}": {
"get": {
"description": "Fetch runs by camera and program.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Industrial"
],
"summary": "/industrial/vision/runs/{camera_id}/{program_id}/{started_at_ms}",
"operationId": "getVisionRunsByCameraAndProgram",
"parameters": [
{
"$ref": "#/parameters/visionCameraIdParam"
},
{
"$ref": "#/parameters/visionProgramIdPathParam"
},
{
"$ref": "#/parameters/visionStartAtMsPathParam"
},
{
"$ref": "#/parameters/visionIncludeParam"
}
],
"responses": {
"200": {
"description": "Return runs by camera ID and program ID.",
"schema": {
"$ref": "#/definitions/VisionRunsByCameraAndProgramResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/machines/history": {
"post": {
"description": "Get historical data for machine objects. This method returns a set of historical data for all machines",
"tags": [
"Industrial"
],
"summary": "/machines/history",
"operationId": "getMachinesHistory",
"parameters": [
{
"description": "Time range to query for events",
"name": "historyParam",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"startMs",
"endMs"
],
"properties": {
"endMs": {
"description": "End of the time range, specified in milliseconds UNIX time.",
"type": "integer",
"example": 1462881998034
},
"startMs": {
"description": "Beginning of the time range, specified in milliseconds UNIX time.",
"type": "integer",
"example": 1462878398034
}
}
}
}
],
"responses": {
"200": {
"description": "List of machine results objects, each containing a time and a datapoint.",
"schema": {
"$ref": "#/definitions/MachineHistoryResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/machines/list": {
"post": {
"description": "Get machine objects. This method returns a list of the machine objects in the Samsara Cloud and information about them.",
"tags": [
"Industrial"
],
"summary": "/machines/list",
"operationId": "getMachines",
"responses": {
"200": {
"description": "List of machine objects.",
"schema": {
"type": "object",
"properties": {
"machines": {
"type": "array",
"items": {
"$ref": "#/definitions/Machine"
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/sensors/cargo": {
"post": {
"description": "Get cargo monitor status (empty / full) for requested sensors.",
"tags": [
"Sensors"
],
"summary": "/sensors/cargo",
"operationId": "getSensorsCargo",
"parameters": [
{
"$ref": "#/parameters/sensorParam"
}
],
"responses": {
"200": {
"description": "List of sensor objects containing the current cargo status reported by each sensor.",
"schema": {
"$ref": "#/definitions/CargoResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/sensors/door": {
"post": {
"description": "Get door monitor status (closed / open) for requested sensors.",
"tags": [
"Sensors"
],
"summary": "/sensors/door",
"operationId": "getSensorsDoor",
"parameters": [
{
"$ref": "#/parameters/sensorParam"
}
],
"responses": {
"200": {
"description": "List of sensor objects containing the current door status reported by each sensor.",
"schema": {
"$ref": "#/definitions/DoorResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/sensors/history": {
"post": {
"description": "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.",
"tags": [
"Sensors"
],
"summary": "/sensors/history",
"operationId": "getSensorsHistory",
"parameters": [
{
"description": "Time range and resolution, and list of sensor ID, field pairs to query.",
"name": "historyParam",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"startMs",
"endMs",
"stepMs",
"series"
],
"properties": {
"endMs": {
"description": "End of the time range, specified in milliseconds UNIX time.",
"type": "integer",
"example": 1462881998034
},
"fillMissing": {
"type": "string",
"default": "withNull",
"enum": [
"withNull",
"withPrevious"
]
},
"series": {
"type": "array",
"maxItems": 40,
"items": {
"description": "Sensor ID and field to query.",
"type": "object",
"required": [
"widgetId",
"field"
],
"properties": {
"field": {
"description": "Field to query.",
"type": "string",
"enum": [
"ambientTemperature",
"cargoPercent",
"currentLoop1Raw",
"currentLoop1Mapped",
"currentLoop2Raw",
"currentLoop2Mapped",
"doorClosed",
"humidity",
"pmPowerTotal",
"pmPhase1Power",
"pmPhase2Power",
"pmPhase3Power",
"pmPhase1PowerFactor",
"pmPhase2PowerFactor",
"pmPhase3PowerFactor",
"probeTemperature"
],
"example": "ambientTemperature"
},
"widgetId": {
"description": "Sensor ID to query.",
"type": "integer",
"format": "int64",
"example": 1
}
}
}
},
"startMs": {
"description": "Beginning of the time range, specified in milliseconds UNIX time.",
"type": "integer",
"example": 1462878398034
},
"stepMs": {
"description": "Time resolution for which data should be returned, in milliseconds. Specifying 3600000 will return data at hour intervals.",
"type": "integer",
"example": 3600000
}
}
}
}
],
"responses": {
"200": {
"description": "List of results objects, each containing a time and a datapoint for each requested sensor/field pair.",
"schema": {
"$ref": "#/definitions/SensorHistoryResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/sensors/humidity": {
"post": {
"description": "Get humidity for requested sensors. This method returns the current relative humidity for the requested sensors.",
"tags": [
"Sensors"
],
"summary": "/sensors/humidity",
"operationId": "getSensorsHumidity",
"parameters": [
{
"$ref": "#/parameters/sensorParam"
}
],
"responses": {
"200": {
"description": "List of sensor objects containing the current humidity reported by each sensor.",
"schema": {
"$ref": "#/definitions/HumidityResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/sensors/list": {
"post": {
"description": "Get sensor objects. This method returns a list of the sensor objects in the Samsara Cloud and information about them.",
"tags": [
"Sensors"
],
"summary": "/sensors/list",
"operationId": "getSensors",
"responses": {
"200": {
"description": "List of sensor objects.",
"schema": {
"type": "object",
"properties": {
"sensors": {
"type": "array",
"items": {
"$ref": "#/definitions/Sensor"
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/sensors/temperature": {
"post": {
"description": "Get temperature for requested sensors. This method returns the current ambient temperature (and probe temperature if applicable) for the requested sensors.",
"tags": [
"Sensors"
],
"summary": "/sensors/temperature",
"operationId": "getSensorsTemperature",
"parameters": [
{
"$ref": "#/parameters/sensorParam"
}
],
"responses": {
"200": {
"description": "List of sensor objects containing the current temperature reported by each sensor.",
"schema": {
"$ref": "#/definitions/TemperatureResponse"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/tags": {
"get": {
"description": "Fetch all of the tags.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Tags"
],
"summary": "/tags",
"operationId": "getAllTags",
"responses": {
"200": {
"description": "List of tags.",
"schema": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"$ref": "#/definitions/Tag"
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"post": {
"description": "Create a new tag.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Tags"
],
"summary": "/tags",
"operationId": "createTag",
"parameters": [
{
"$ref": "#/parameters/tagCreateParam"
}
],
"responses": {
"200": {
"description": "Newly created tag object, including the new tag ID.",
"schema": {
"$ref": "#/definitions/Tag"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/tags/{tag_id}": {
"get": {
"description": "Fetch a tag by id.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Tags"
],
"summary": "/tags/{tag_id}",
"operationId": "getTagById",
"parameters": [
{
"$ref": "#/parameters/tagPathParam"
}
],
"responses": {
"200": {
"description": "The tag corresponding to tag_id.",
"schema": {
"$ref": "#/definitions/Tag"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"put": {
"description": "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.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Tags"
],
"summary": "/tags/{tag_id}",
"operationId": "updateTagById",
"parameters": [
{
"$ref": "#/parameters/tagPathParam"
},
{
"$ref": "#/parameters/tagUpdateParam"
}
],
"responses": {
"200": {
"description": "The updated tag data.",
"schema": {
"$ref": "#/definitions/Tag"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"delete": {
"description": "Permanently deletes a tag.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Tags"
],
"summary": "/tags/{tag_id}",
"operationId": "deleteTagById",
"parameters": [
{
"$ref": "#/parameters/tagPathParam"
}
],
"responses": {
"200": {
"description": "Successfully deleted the tag. No response body is returned."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"patch": {
"description": "Add or delete specific members from a tag, or modify the name of a tag.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Tags"
],
"summary": "/tags/{tag_id}",
"operationId": "modifyTagById",
"parameters": [
{
"$ref": "#/parameters/tagPathParam"
},
{
"$ref": "#/parameters/tagModifyParam"
}
],
"responses": {
"200": {
"description": "The updated tag data.",
"schema": {
"$ref": "#/definitions/Tag"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/user_roles": {
"get": {
"description": "Get all roles in the organization.",
"tags": [
"Users"
],
"summary": "/user_roles",
"operationId": "listUserRoles",
"responses": {
"200": {
"description": "List of user roles.",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/UserRole"
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/users": {
"get": {
"description": "List all users in the organization.",
"tags": [
"Users"
],
"summary": "/users",
"operationId": "listUsers",
"responses": {
"200": {
"description": "List of users.",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/User"
}
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"post": {
"description": "Add a user to the organization.",
"tags": [
"Users"
],
"summary": "/users",
"operationId": "createUser",
"parameters": [
{
"$ref": "#/parameters/createUserParam"
}
],
"responses": {
"200": {
"description": "User successfully created.",
"schema": {
"$ref": "#/definitions/User"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
},
"/v1/users/{userId}": {
"get": {
"description": "Get a user.",
"tags": [
"Users"
],
"summary": "/users/{userId}",
"operationId": "getUserById",
"parameters": [
{
"$ref": "#/parameters/createUserParam"
},
{
"type": "integer",
"format": "int64",
"description": "ID of the user. Must contain only digits 0-9.",
"name": "userId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "User record.",
"schema": {
"$ref": "#/definitions/User"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"delete": {
"description": "Remove a user from the organization.",
"tags": [
"Users"
],
"summary": "/users/{userId}",
"operationId": "deleteUserById",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "ID of the user. Must contain only digits 0-9.",
"name": "userId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The user was successfully removed."
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
},
"patch": {
"description": "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.",
"tags": [
"Users"
],
"summary": "/users/{userId}",
"operationId": "patchUser",
"parameters": [
{
"$ref": "#/parameters/updateUserParam"
},
{
"type": "integer",
"format": "int64",
"description": "ID of the user. Must contain only digits 0-9.",
"name": "userId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "User successfully updated.",
"schema": {
"$ref": "#/definitions/User"
}
},
"default": {
"description": "Unexpected error.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
}
}
}
},
"definitions": {
"Address": {
"description": "Information about an address/geofence. Geofences are either a circle or a polygon.",
"type": "object",
"properties": {
"contacts": {
"type": "array",
"items": {
"$ref": "#/definitions/Contact"
}
},
"createdAtTime": {
"description": "The date and time this address was created in RFC 3339 format.",
"type": "string",
"format": "date-time",
"example": "2019-05-18T20:27:35Z"
},
"formattedAddress": {
"description": "The full address associated with this address/geofence, as it might be recognized by maps.google.com",
"type": "string",
"example": "350 Rhode Island St, San Francisco, CA"
},
"geofence": {
"$ref": "#/definitions/AddressGeofence"
},
"id": {
"description": "ID of the address",
"type": "integer",
"format": "int64",
"example": 123
},
"name": {
"description": "Name of the address or geofence",
"type": "string",
"example": "Samsara HQ"
},
"notes": {
"$ref": "#/definitions/AddressNotes"
},
"tags": {
"type": "array",
"items": {
"$ref": "#/definitions/TagMetadata"
}
}
}
},
"AddressGeofence": {
"description": "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.",
"type": "object",
"properties": {
"circle": {
"description": "Information about a circular geofence. This field is only populated if the geofence is a circle.",
"type": "object",
"required": [
"radiusMeters"
],
"properties": {
"latitude": {
"description": "The latitude of the center of the circular geofence",
"type": "number",
"format": "double",
"example": 37.765363
},
"longitude": {
"description": "The longitude of the center of the circular geofence",
"type": "number",
"format": "double",
"example": -122.403098
},
"radiusMeters": {
"description": "The radius of the circular geofence",
"type": "number",
"format": "integer",
"example": 250
}
}
},
"polygon": {
"description": "Information about a polygon geofence. This field is only populated if the geofence is a polygon.",
"type": "object",
"required": [
"vertices"
],
"properties": {
"vertices": {
"description": "The vertices of the polygon geofence. These geofence vertices describe the perimeter of the polygon, and must consist of at least 3 vertices and less than 40.",
"type": "array",
"items": {
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"description": "The longitude of a geofence vertex",
"type": "number",
"format": "double",
"example": 37.765363
},
"longitude": {
"description": "The longitude of a geofence vertex",
"type": "number",
"format": "double",
"example": -122.403098
}
}
}
}
}
}
}
},
"AddressNotes": {
"description": "Notes associated with an address.",
"type": "string",
"example": "Delivery site 1"
},
"Asset": {
"description": "Basic information of an asset",
"type": "object",
"required": [
"id"
],
"properties": {
"assetSerialNumber": {
"description": "Serial number of the host asset",
"type": "string",
"example": "SNTEST123"
},
"cable": {
"description": "The cable connected to the asset",
"type": "object",
"properties": {
"assetType": {
"description": "Asset type",
"type": "string",
"example": "Thermo King"
}
}
},
"engineHours": {
"description": "Engine hours",
"type": "integer",
"example": 104
},
"id": {
"description": "Asset ID",
"type": "integer",
"format": "int64",
"example": 1
},
"name": {
"description": "Asset name",
"type": "string",
"example": "Trailer 123"
},
"vehicleId": {
"description": "The ID of the Vehicle associated to the Asset (if present)",
"type": "integer",
"format": "int64",
"example": 2
}
}
},
"AssetCurrentLocation": {
"description": "Current location of an asset",
"type": "object",
"properties": {
"latitude": {
"description": "The latitude of the location in degrees.",
"type": "number",
"example": 37
},
"location": {
"description": "The best effort (street,city,state) for the latitude and longitude.",
"type": "string",
"example": "525 York, San Francisco, CA"
},
"longitude": {
"description": "The longitude of the location in degrees.",
"type": "number",
"example": -122.7
},
"speedMilesPerHour": {
"description": "The speed calculated from GPS that the asset was traveling at in miles per hour.",
"type": "number",
"example": 35
},
"timeMs": {
"description": "Time in Unix milliseconds since epoch when the asset was at the location.",
"type": "number",
"example": 12314151
}
}
},
"AssetCurrentLocationsResponse": {
"description": "Basic information of an asset",
"type": "object",
"required": [
"id"
],
"properties": {
"assetSerialNumber": {
"description": "Asset serial number",
"type": "string",
"example": "8dka2810"
},
"cable": {
"description": "The cable connected to the asset",
"type": "object",
"properties": {
"assetType": {
"description": "Asset type",
"type": "string",
"example": "Thermo King"
}
}
},
"engineHours": {
"description": "Engine hours",
"type": "integer",
"example": 104
},
"id": {
"description": "Asset ID",
"type": "integer",
"format": "int64",
"example": 1
},
"location": {
"description": "Current location of an asset",
"type": "array",
"items": {
"$ref": "#/definitions/AssetCurrentLocation"
}
},
"name": {
"description": "Asset name",
"type": "string",
"example": "Trailer 123"
}
}
},
"AssetLocationResponse": {
"description": "A list of historical asset locations.",
"type": "array",
"items": {
"description": "Asset location details.",
"type": "object",
"properties": {
"latitude": {
"description": "The latitude of the location in degrees.",
"type": "number",
"example": 37
},
"location": {
"description": "The best effort (street,city,state) for the latitude and longitude.",
"type": "string",
"example": "525 York, San Francisco, CA"
},
"longitude": {
"description": "The longitude of the location in degrees.",
"type": "number",
"example": -122.7
},
"speedMilesPerHour": {
"description": "The speed calculated from GPS that the asset was traveling at in miles per hour.",
"type": "number",
"example": 35
},
"time": {
"description": "Time in Unix milliseconds since epoch when the asset was at the location.",
"type": "number",
"example": 12314151
}
}
}
},
"AssetReeferResponse": {
"description": "Reefer-specific asset details",
"type": "object",
"properties": {
"assetType": {
"description": "Asset type",
"type": "string",
"example": "Thermo King"
},
"id": {
"description": "Asset ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Asset name",
"type": "string",
"example": "Reefer 123"
},
"reeferStats": {
"type": "object",
"properties": {
"alarms": {
"description": "Reefer alarms",
"type": "array",
"items": {
"type": "object",
"properties": {
"alarms": {
"type": "array",
"items": {
"type": "object",
"properties": {
"alarmCode": {
"description": "ID of the alarm",
"type": "integer",
"format": "int64",
"example": 102
},
"description": {
"description": "Description of the alarm",
"type": "string",
"example": "Check Return Air Sensor"
},
"operatorAction": {
"description": "Recommended operator action",
"type": "string",
"example": "Check and repair at end of trip"
},
"severity": {
"description": "Severity of the alarm: 1: OK to run, 2: Check as specified, 3: Take immediate action",
"type": "integer",
"format": "int64",
"example": 1
}
}
}
},
"changedAtMs": {
"description": "Timestamp when the alarms were reported, in Unix milliseconds since epoch",
"type": "integer",
"format": "int64",
"example": 1453449599999
}
}
}
},
"engineHours": {
"description": "Engine hours of the reefer",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"engineHours": {
"description": "Engine hours of the reefer.",
"type": "integer",
"format": "int64",
"example": 1200
}
}
}
},
"fuelPercentage": {
"description": "Fuel percentage of the reefer",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"fuelPercentage": {
"description": "Fuel percentage of the reefer.",
"type": "integer",
"format": "int64",
"example": 99
}
}
}
},
"powerStatus": {
"description": "Power status of the reefer",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"status": {
"description": "Power status of the reefer.",
"type": "string",
"example": "Active (Continuous)"
}
}
}
},
"returnAirTemp": {
"description": "Return air temperature of the reefer",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"tempInMilliC": {
"description": "Return air temperature in millidegree Celsius.",
"type": "integer",
"format": "int64",
"example": 31110
}
}
}
},
"setPoint": {
"description": "Set point temperature of the reefer",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"tempInMilliC": {
"description": "Set point temperature in millidegree Celsius.",
"type": "integer",
"format": "int64",
"example": 31110
}
}
}
}
}
}
}
},
"AssetsReefer": {
"description": "Reefer-specific details",
"type": "object",
"properties": {
"assetType": {
"description": "Asset type",
"type": "string",
"example": "Thermo King"
},
"id": {
"description": "Asset ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Asset name",
"type": "string",
"example": "Reefer 123"
},
"reeferStats": {
"description": "Contains all the state changes of the reefer for the included stat types. Each state change is recorded independently, so the number of records in each array may differ depending on when that stat changed state. Stat types with a continuous value (such as temperature) will be recorded at different rates depending on the reefer, but generally readings have a frequency on the order of seconds.",
"type": "object",
"properties": {
"ambientAirTemperature": {
"description": "Ambient temperature of the reefer. This is the temperature of the air around the Samsara Asset Gateway.",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"tempInMilliC": {
"description": "Ambient temperature in millidegree Celsius.",
"type": "integer",
"format": "int64",
"example": 31110
}
}
}
},
"dischargeAirTemperature": {
"description": "Discharge air temperature of the reefer. This is the temperature of the air as it leaves the cooling unit.",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"tempInMilliC": {
"description": "Discharge temperature in millidegree Celsius.",
"type": "integer",
"format": "int64",
"example": 31110
}
}
}
},
"engineHours": {
"description": "Engine hours of the reefer",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"engineHours": {
"description": "Engine hours of the reefer.",
"type": "integer",
"format": "int64",
"example": 1200
}
}
}
},
"fuelPercentage": {
"description": "Fuel percentage of the reefer",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"fuelPercentage": {
"description": "Fuel percentage of the reefer.",
"type": "integer",
"format": "int64",
"example": 99
}
}
}
},
"powerStatus": {
"description": "Power status of the reefer",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"status": {
"description": "Power status of the reefer.",
"type": "string",
"enum": [
"Off",
"Active",
"Active (Start/Stop)",
"Active (Continuous)"
],
"example": "Active (Continuous)"
}
}
}
},
"reeferAlarms": {
"description": "Reefer alarms",
"type": "array",
"items": {
"type": "object",
"properties": {
"alarms": {
"type": "array",
"items": {
"type": "object",
"properties": {
"alarmCode": {
"description": "ID of the alarm",
"type": "integer",
"format": "int64",
"example": 102
},
"description": {
"description": "Description of the alarm",
"type": "string",
"example": "Check Return Air Sensor"
},
"operatorAction": {
"description": "Recommended operator action",
"type": "string",
"example": "Check and repair at end of trip"
},
"severity": {
"description": "Severity of the alarm: 1: OK to run, 2: Check as specified, 3: Take immediate action",
"type": "integer",
"format": "int64",
"example": 1
}
}
}
},
"changedAtMs": {
"description": "Timestamp when the alarms were reported, in Unix milliseconds since epoch",
"type": "integer",
"format": "int64",
"example": 1453449599999
}
}
}
},
"returnAirTemperature": {
"description": "Return air temperature of the reefer. This is the temperature read by the reefer module (Carrier, Thermo King) that shows the temperature of the air as it enters the system.",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"tempInMilliC": {
"description": "Return air temperature in millidegree Celsius.",
"type": "integer",
"format": "int64",
"example": 31110
}
}
}
},
"setPoint": {
"description": "Set point temperature of the reefer",
"type": "array",
"items": {
"type": "object",
"properties": {
"changedAtMs": {
"description": "Timestamp in Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"tempInMilliC": {
"description": "Set point temperature in millidegree Celsius.",
"type": "integer",
"format": "int64",
"example": 31110
}
}
}
}
}
}
}
},
"AuxInput": {
"description": "Digital value of an aux input.",
"type": "object",
"required": [
"timeMs",
"value"
],
"properties": {
"timeMs": {
"description": "Timestamp in Unix epoch milliseconds.",
"type": "number",
"format": "int64",
"example": 1546542978484
},
"value": {
"description": "Boolean representing the digital value of the aux input.",
"type": "boolean",
"example": true
}
}
},
"AuxInputSeries": {
"description": "A list of aux input values over a timerange.",
"type": "object",
"required": [
"name",
"values"
],
"properties": {
"name": {
"description": "The name of the aux input.",
"type": "string",
"enum": [
"Emergency Lights",
"Emergency Alarm",
"Stop Paddle",
"Power Take-Off",
"Plow",
"Sweeper",
"Salter",
"Boom"
],
"example": "Boom"
},
"values": {
"type": "array",
"items": {
"$ref": "#/definitions/AuxInput"
}
}
}
},
"CargoResponse": {
"description": "Contains the current cargo status of a sensor.",
"type": "object",
"properties": {
"groupId": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 101
},
"sensors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"cargoEmpty": {
"description": "Flag indicating whether the current cargo is empty or loaded.",
"type": "boolean",
"example": true
},
"cargoStatusTime": {
"description": "The timestamp of reported cargo status, specified in RFC 3339 time.",
"type": "string",
"example": "2019-04-17T16:42:55Z"
},
"id": {
"description": "ID of the sensor.",
"type": "integer",
"format": "int64",
"example": 122
},
"name": {
"description": "Name of the sensor.",
"type": "string",
"example": "Trailer Cargo Sensor"
},
"trailerId": {
"description": "ID of the trailer associated with the sensor for the data point. If no trailer is connected, this parameter will not be reported.",
"type": "integer",
"example": 123
},
"vehicleId": {
"description": "ID of the vehicle associated with the sensor for the data point. If no vehicle is connected, this parameter will not be reported.",
"type": "integer",
"example": 124
}
}
}
}
}
},
"Contact": {
"description": "Information about a notification contact for alerts.",
"type": "object",
"properties": {
"email": {
"description": "Email address of the contact.",
"type": "string",
"example": "jane.jones@yahoo.com"
},
"firstName": {
"description": "First name of the contact.",
"type": "string",
"example": "Jane"
},
"id": {
"description": "ID of the contact.",
"type": "integer",
"format": "int64",
"example": 123
},
"lastName": {
"description": "Last name of the contact.",
"type": "string",
"example": "Jones"
},
"phone": {
"description": "Phone number of the contact.",
"type": "string",
"example": "111-222-3344"
}
}
},
"ContactData": {
"description": "Information about a notification contact for alerts.",
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/Contact"
}
}
},
"ContactIds": {
"description": "A list of IDs for contact book entries.",
"type": "array",
"items": {
"type": "number",
"format": "int64",
"example": 123
}
},
"ContactInput": {
"description": "Information for adding a notification contact for alerts.",
"type": "object",
"properties": {
"email": {
"description": "Email address of the contact.",
"type": "string",
"example": "jane.jones@yahoo.com"
},
"firstName": {
"description": "First name of the contact.",
"type": "string",
"example": "Jane"
},
"lastName": {
"description": "Last name of the contact.",
"type": "string",
"example": "Jones"
},
"phone": {
"description": "Phone number of the contact.",
"type": "string",
"example": "111-222-3344"
}
}
},
"CurrentDriver": {
"$ref": "#/definitions/Driver"
},
"DataInputHistoryResponse": {
"type": "object",
"required": [
"name"
],
"properties": {
"id": {
"description": "The ID of this data input",
"type": "integer",
"format": "int64",
"example": 12345
},
"name": {
"description": "Name of this data input",
"type": "string",
"example": "Pump Flow"
},
"points": {
"description": "Data points from this data input",
"type": "array",
"items": {
"type": "object",
"properties": {
"timeMs": {
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"value": {
"type": "number",
"format": "double",
"example": 12.332
}
}
}
}
}
},
"DispatchJob": {
"allOf": [
{
"type": "object",
"required": [
"id",
"dispatch_route_id",
"job_state"
],
"properties": {
"arrived_at_ms": {
"description": "The time at which the driver arrived at the job destination.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"completed_at_ms": {
"description": "The time at which the job was marked complete (e.g. started driving to the next destination).",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"dispatch_route_id": {
"description": "ID of the route that this job belongs to.",
"type": "integer",
"format": "int64",
"example": 55
},
"documents": {
"description": "Document submissions associated with this job.",
"type": "array",
"items": {
"$ref": "#/definitions/DispatchJobDocumentInfo"
}
},
"driver_id": {
"description": "ID of the driver assigned to the dispatch job.",
"type": "integer",
"format": "int64",
"example": 444
},
"en_route_at_ms": {
"description": "The time at which the assigned driver started fulfilling the job (e.g. started driving to the destination).",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"estimated_arrival_ms": {
"description": "The time at which the assigned driver is estimated to arrive at the job destination. Only valid for en-route jobs.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"fleet_viewer_url": {
"description": "Fleet viewer url of the dispatch job.",
"type": "string",
"example": "https://cloud.samsara.com/fleet/viewer/job/fleet_viewer_token"
},
"group_id": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 101
},
"id": {
"description": "ID of the Samsara dispatch job.",
"type": "integer",
"format": "int64",
"example": 773
},
"job_state": {
"$ref": "#/definitions/jobStatus"
},
"skipped_at_ms": {
"description": "The time at which the job was marked skipped.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"vehicle_id": {
"description": "ID of the vehicle used for the dispatch job.",
"type": "integer",
"format": "int64",
"example": 112
}
}
},
{
"$ref": "#/definitions/DispatchJobCreate"
}
]
},
"DispatchJobCreate": {
"type": "object",
"required": [
"scheduled_arrival_time_ms"
],
"properties": {
"destination_address": {
"description": "The address of the job destination, as it would be recognized if provided to maps.google.com. Optional if a valid destination address ID is provided.",
"type": "string",
"example": "123 Main St, Philadelphia, PA 19106"
},
"destination_address_id": {
"description": "ID of the job destination associated with an address book entry. Optional if valid values are provided for destination address and latitude/longitude. If a valid destination 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 destination name is not provided.",
"type": "integer",
"format": "int64",
"example": 67890
},
"destination_lat": {
"description": "Latitude of the destination in decimal degrees. Optional if a valid destination address ID is provided.",
"type": "number",
"format": "double",
"example": 123.456
},
"destination_lng": {
"description": "Longitude of the destination in decimal degrees. Optional if a valid destination address ID is provided.",
"type": "number",
"format": "double",
"example": 37.459
},
"destination_name": {
"description": "The name of the job destination. If provided, it will take precedence over the name of the address book entry.",
"type": "string",
"example": "ACME Inc. Philadelphia HQ"
},
"external_ids": {
"$ref": "#/definitions/ExternalIDs"
},
"notes": {
"description": "Notes regarding the details of this job, maximum of 2000 characters; newline characters ('\\n')can be used for formatting.",
"type": "string",
"example": "Ensure crates are stacked no more than 3 high."
},
"scheduled_arrival_time_ms": {
"description": "The time at which the assigned driver is scheduled to arrive at the job destination.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"scheduled_departure_time_ms": {
"description": "The time at which the assigned driver is scheduled to depart from the job destination.",
"type": "integer",
"format": "int64",
"example": 1462881998034
}
}
},
"DispatchJobDocumentInfo": {
"type": "object",
"required": [
"driverId",
"id"
],
"properties": {
"driverId": {
"description": "ID of driver that submitted the document.",
"type": "integer",
"example": 1234
},
"id": {
"description": "ID of document. This can be used to query for the document's info via the /v1/fleet/drivers/{driver_id}/documents/{document_id} endpoint",
"type": "string",
"example": "2018_42424242"
}
}
},
"DispatchJobUpdate": {
"allOf": [
{
"type": "object",
"required": [
"id",
"dispatch_jobs"
],
"properties": {
"id": {
"description": "ID of the Samsara dispatch job to update",
"type": "integer",
"format": "int64",
"example": 42
}
}
},
{
"$ref": "#/definitions/DispatchJobCreate"
}
]
},
"DispatchJobWithoutETA": {
"allOf": [
{
"type": "object",
"required": [
"id",
"dispatch_route_id",
"job_state"
],
"properties": {
"arrived_at_ms": {
"description": "The time at which the driver arrived at the job destination.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"completed_at_ms": {
"description": "The time at which the job was marked complete (e.g. started driving to the next destination).",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"dispatch_route_id": {
"description": "ID of the route that this job belongs to.",
"type": "integer",
"format": "int64",
"example": 55
},
"documents": {
"description": "Document submissions associated with this job.",
"type": "array",
"items": {
"$ref": "#/definitions/DispatchJobDocumentInfo"
}
},
"driver_id": {
"description": "ID of the driver assigned to the dispatch job.",
"type": "integer",
"format": "int64",
"example": 444
},
"en_route_at_ms": {
"description": "The time at which the assigned driver started fulfilling the job (e.g. started driving to the destination).",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"fleet_viewer_url": {
"description": "Fleet viewer url of the dispatch job.",
"type": "string",
"example": "https://cloud.samsara.com/fleet/viewer/job/fleet_viewer_token"
},
"group_id": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 101
},
"id": {
"description": "ID of the Samsara dispatch job.",
"type": "integer",
"format": "int64",
"example": 773
},
"job_state": {
"$ref": "#/definitions/jobStatus"
},
"skipped_at_ms": {
"description": "The time at which the job was marked skipped.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"vehicle_id": {
"description": "ID of the vehicle used for the dispatch job.",
"type": "integer",
"format": "int64",
"example": 112
}
}
},
{
"$ref": "#/definitions/DispatchJobCreate"
}
]
},
"DispatchRoute": {
"allOf": [
{
"type": "object",
"properties": {
"dispatch_jobs": {
"description": "The dispatch jobs associated with this route.",
"type": "array",
"items": {
"$ref": "#/definitions/DispatchJob"
}
},
"id": {
"description": "ID of the Samsara dispatch route.",
"type": "integer",
"format": "int64",
"example": 556
}
}
},
{
"$ref": "#/definitions/DispatchRouteBase"
}
]
},
"DispatchRouteBase": {
"type": "object",
"properties": {
"actual_end_ms": {
"description": "The time in Unix epoch milliseconds that the route actually ended.",
"type": "integer",
"format": "int64",
"example": 1462882101000
},
"actual_start_ms": {
"description": "The time in Unix epoch milliseconds that the route actually started.",
"type": "integer",
"format": "int64",
"example": 1462882098000
},
"complete_last_stop_on_arrival": {
"description": "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.",
"type": "boolean",
"default": true
},
"driver_id": {
"description": "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.",
"type": "integer",
"format": "int64",
"example": 555
},
"externalIds": {
"$ref": "#/definitions/ExternalIDs"
},
"group_id": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 101
},
"name": {
"description": "Descriptive name of this route.",
"type": "string",
"example": "Bid #123"
},
"notes": {
"description": "Notes regarding the details of this route; maximum of 2000 characters; newline characters ('\\n')can be used for formatting.",
"type": "string",
"example": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23."
},
"odometer_end_meters": {
"description": "Odometer reading at the end of the route. Will not be returned if Route is not completed or if Odometer information is not available for the relevant vehicle.",
"type": "integer",
"format": "int64",
"example": 2000000
},
"odometer_start_meters": {
"description": "Odometer reading at the start of the route. Will not be returned if Route has not started or if Odometer information is not available for the relevant vehicle.",
"type": "integer",
"format": "int64",
"example": 1000000
},
"scheduled_end_ms": {
"description": "The time in Unix epoch milliseconds that the last job in the route is scheduled to end.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"scheduled_meters": {
"description": "The distance expected to be traveled for this route in meters.",
"type": "integer",
"format": "int64",
"example": 10000
},
"scheduled_start_ms": {
"description": "The time in Unix epoch milliseconds that the route is scheduled to start.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"start_location_address": {
"description": "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.",
"type": "string",
"example": "123 Main St, Philadelphia, PA 19106"
},
"start_location_address_id": {
"description": "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.",
"type": "integer",
"format": "int64",
"example": 67890
},
"start_location_lat": {
"description": "Latitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.",
"type": "number",
"format": "double",
"example": 123.456
},
"start_location_lng": {
"description": "Longitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.",
"type": "number",
"format": "double",
"example": 37.459
},
"start_location_name": {
"description": "The name of the route's starting location. If provided, it will take precedence over the name of the address book entry.",
"type": "string",
"example": "ACME Inc. Philadelphia HQ"
},
"trailer_id": {
"description": "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.",
"type": "integer",
"format": "int64",
"example": 666
},
"vehicle_id": {
"description": "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.",
"type": "integer",
"format": "int64",
"example": 444
}
}
},
"DispatchRouteCreate": {
"allOf": [
{
"type": "object",
"required": [
"dispatch_jobs"
],
"properties": {
"dispatch_jobs": {
"description": "The dispatch jobs to create for this route.",
"type": "array",
"items": {
"$ref": "#/definitions/DispatchJobCreate"
}
}
}
},
{
"$ref": "#/definitions/DispatchRouteCreateBase"
}
]
},
"DispatchRouteCreateBase": {
"type": "object",
"required": [
"name",
"scheduled_start_ms"
],
"properties": {
"complete_last_stop_on_arrival": {
"description": "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.",
"type": "boolean",
"default": true
},
"driver_id": {
"description": "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.",
"type": "integer",
"format": "int64",
"example": 555
},
"externalIds": {
"$ref": "#/definitions/ExternalIDs"
},
"name": {
"description": "Descriptive name of this route.",
"type": "string",
"example": "Bid #123"
},
"notes": {
"description": "Notes regarding the details of this route; maximum of 2000 characters; newline characters ('\\n')can be used for formatting.",
"type": "string",
"example": "Please make sure to confirm crate count at each stop on this route.\nTotal number of crates for route: 23."
},
"scheduled_end_ms": {
"description": "The time in Unix epoch milliseconds that the last job in the route is scheduled to end.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"scheduled_meters": {
"description": "The distance expected to be traveled for this route in meters.",
"type": "integer",
"format": "int64",
"example": 10000
},
"scheduled_start_ms": {
"description": "The time in Unix epoch milliseconds that the route is scheduled to start.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"start_location_address": {
"description": "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.",
"type": "string",
"example": "123 Main St, Philadelphia, PA 19106"
},
"start_location_address_id": {
"description": "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.",
"type": "integer",
"format": "int64",
"example": 67890
},
"start_location_lat": {
"description": "Latitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.",
"type": "number",
"format": "double",
"example": 123.456
},
"start_location_lng": {
"description": "Longitude of the start location in decimal degrees. Optional if a valid start location address ID is provided.",
"type": "number",
"format": "double",
"example": 37.459
},
"start_location_name": {
"description": "The name of the route's starting location. If provided, it will take precedence over the name of the address book entry.",
"type": "string",
"example": "ACME Inc. Philadelphia HQ"
},
"trailer_id": {
"description": "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.",
"type": "integer",
"format": "int64",
"example": 666
},
"vehicle_id": {
"description": "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.",
"type": "integer",
"format": "int64",
"example": 444
}
}
},
"DispatchRouteHistoricalEntry": {
"type": "object",
"properties": {
"changed_at_ms": {
"description": "Timestamp that the route was updated, represented as Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1499411220000
},
"route": {
"$ref": "#/definitions/DispatchRoute"
}
}
},
"DispatchRouteHistory": {
"type": "object",
"properties": {
"history": {
"description": "History of the route's state changes.",
"type": "array",
"items": {
"$ref": "#/definitions/DispatchRouteHistoricalEntry"
}
}
}
},
"DispatchRouteUpdate": {
"allOf": [
{
"type": "object",
"required": [
"dispatch_jobs"
],
"properties": {
"dispatch_jobs": {
"description": "The dispatch jobs for the route.",
"type": "array",
"items": {
"$ref": "#/definitions/DispatchJobUpdate"
}
}
}
},
{
"$ref": "#/definitions/DispatchRouteUpdateBase"
}
]
},
"DispatchRouteUpdateBase": {
"allOf": [
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "ID of route. This must match the route ID passed in URL.",
"type": "integer",
"format": "int64",
"example": "42"
}
}
},
{
"$ref": "#/definitions/DispatchRouteCreateBase"
}
]
},
"DispatchRouteWithoutETA": {
"allOf": [
{
"type": "object",
"properties": {
"dispatch_jobs": {
"description": "The dispatch jobs associated with this route.",
"type": "array",
"items": {
"$ref": "#/definitions/DispatchJobWithoutETA"
}
},
"id": {
"description": "ID of the Samsara dispatch route.",
"type": "integer",
"format": "int64",
"example": 556
}
}
},
{
"$ref": "#/definitions/DispatchRouteBase"
}
]
},
"DispatchRoutes": {
"type": "array",
"items": {
"$ref": "#/definitions/DispatchRoute"
}
},
"Document": {
"allOf": [
{
"type": "object",
"required": [
"orgId",
"driverId",
"id",
"driverCreatedAtMs",
"serverCreatedAtMs",
"serverUpdatedAtMs",
"documentType",
"vehicleId",
"fields"
],
"properties": {
"documentType": {
"description": "Name of the document type.",
"type": "string",
"example": "Fuel Receipt"
},
"driverCreatedAtMs": {
"description": "The time in Unix epoch milliseconds that the document was created in the driver app.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"driverId": {
"description": "ID of the driver for whom the document is submitted.",
"type": "integer",
"format": "int64",
"example": 555
},
"fields": {
"$ref": "#/definitions/DocumentFetchFields"
},
"id": {
"description": "ID of the document.",
"type": "string",
"example": "2018_42424242"
},
"orgId": {
"description": "Organization ID that the document belongs to.",
"type": "integer",
"format": "int64",
"example": 555
},
"serverCreatedAtMs": {
"description": "The time in Unix epoch milliseconds that the document was received by the server.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"serverUpdatedAtMs": {
"description": "The time in Unix epoch milliseconds that the document was updated on the server.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"vehicleId": {
"description": "ID of the vehicle the driver was signed into when the document was submitted. Will be `null` if the document `state` is `Required`.",
"type": "integer",
"format": "int64",
"example": 222
}
}
},
{
"$ref": "#/definitions/DocumentBase"
}
]
},
"DocumentBase": {
"type": "object",
"required": [
"dispatchJobId",
"notes"
],
"properties": {
"dispatchJobId": {
"description": "ID of the Samsara dispatch job for which the document is submitted.",
"type": "integer",
"format": "int64",
"example": 773
},
"name": {
"description": "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.",
"type": "string",
"maxLength": 255,
"minLength": 1,
"example": "Fuel Receipt Wichita"
},
"notes": {
"description": "Notes submitted with this document.",
"type": "string",
"example": "Fueled up before delivery."
},
"state": {
"description": "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 have been submitted by the driver in the Driver App.",
"type": "string",
"default": "Required",
"enum": [
"Required",
"Submitted"
],
"example": "Submitted"
}
}
},
"DocumentConditionalFieldSection": {
"type": "object",
"required": [
"triggeringFieldIndex",
"triggeringFieldValue",
"conditionalFieldFirstIndex",
"conditionalFieldLastIndex"
],
"properties": {
"conditionalFieldFirstIndex": {
"description": "Index of the end of the conditional field section.",
"type": "integer",
"format": "int64",
"example": 3
},
"conditionalFieldLastIndex": {
"description": "Index of the start of the conditional field section.",
"type": "integer",
"format": "int64",
"example": 2
},
"triggeringFieldIndex": {
"description": "Index of the option select field that triggers one or more conditional fields.",
"type": "integer",
"format": "int64",
"example": 1
},
"triggeringFieldValue": {
"description": "Indicates the option select value that triggers conditional fields.",
"type": "string",
"example": "true"
}
}
},
"DocumentCreate": {
"allOf": [
{
"description": "Arguments to create a document.",
"type": "object",
"required": [
"documentTypeUuid",
"fields"
],
"properties": {
"documentTypeUuid": {
"description": "Universally unique identifier for the document type that this document is being created for.",
"type": "string",
"example": "4aff772c-a7bb-45e6-8e41-6a53e34feb83"
},
"fields": {
"$ref": "#/definitions/DocumentCreateFields"
}
}
},
{
"$ref": "#/definitions/DocumentCreateBase"
}
]
},
"DocumentCreateBase": {
"type": "object",
"properties": {
"dispatchJobId": {
"description": "ID of the Samsara dispatch job for which the document is submitted.",
"type": "integer",
"format": "int64",
"example": 773
},
"name": {
"description": "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.",
"type": "string",
"maxLength": 255,
"minLength": 1,
"example": "Fuel Receipt Wichita"
},
"notes": {
"description": "Notes submitted with this document.",
"type": "string",
"example": "Fueled up before delivery."
},
"state": {
"description": "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.",
"type": "string",
"default": "Required",
"enum": [
"Required",
"Submitted"
],
"example": "Required"
}
}
},
"DocumentCreateField": {
"type": "object",
"properties": {
"dateTimeValue": {
"description": "The value of a `ValueType_DateTime` field. Can be set to null or omitted if the document is in the \"Required\" state.",
"type": "object",
"required": [
"dateTimeMs"
],
"properties": {
"dateTimeMs": {
"description": "The Unix epoch on milliseconds of this date time field.",
"type": "integer",
"format": "int64",
"example": 10855639004823
}
}
},
"multipleChoiceValue": {
"description": "The value of a `ValueType_MultipleChoice` field. Can be set to null or omitted if the document is in the \"Required\" state.",
"type": "array",
"items": {
"type": "object",
"properties": {
"selected": {
"description": "Whether the multiple choice field is selected or not.",
"type": "boolean"
},
"value": {
"description": "The name of the multiple choice field.",
"type": "string"
}
}
}
},
"numberValue": {
"description": "The value of a `ValueType_Number` field. Can be set to null or omitted if the document is in the \"Required\" state.",
"type": "number",
"format": "double",
"example": 12.34
},
"stringValue": {
"description": "The value of a `ValueType_String` field. Can be set to null or omitted if the document is in the \"Required\" state.",
"type": "string",
"example": "This is a string."
},
"valueType": {
"description": "The type of this field.\n\n**Note:** Signature and photo fields are only supported when the document state is set to \"Required\". The values for these fields must be omitted or set to null. For example:\n\n```\n\n\"fields\": [\n\n {\n\n \"label\": \"Signature\",\n\n \"valueType\": \"ValueType_Signature\"\n\n },\n\n ... more fields\n\n]\n\n```",
"type": "string",
"enum": [
"ValueType_Number",
"ValueType_String",
"ValueType_MultipleChoice",
"ValueType_DateTime",
"ValueType_Signature",
"ValueType_Photo"
],
"example": "ValueType_Number"
}
}
},
"DocumentCreateFields": {
"description": "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\".",
"type": "array",
"items": {
"description": "Field item parameters.",
"type": "object",
"required": [
"label",
"valueType"
],
"properties": {
"dateTimeValue": {
"description": "The date time value to populate the field. Use with ValueType_DateTime. Cannot be ommited or set to null",
"type": "object",
"properties": {
"dateTimeMs": {
"type": "number"
}
}
},
"label": {
"description": "label of the field",
"type": "string"
},
"multipleChoiceValue": {
"description": "The multiple choice value to populate the field. Use with ValueType_MultipleChoice. Cannot be ommited or set to null",
"type": "array",
"items": {
"description": "An option item for a multiple choice field",
"type": "object",
"properties": {
"selected": {
"type": "boolean"
},
"value": {
"type": "string"
}
}
}
},
"numberValue": {
"description": "The number value to populate the field. Use with ValueType_Number. Can be ommited or set to null",
"type": "number"
},
"stringValue": {
"description": "The string value to populate the field. Use with ValueType_String. Can be ommited or set to null",
"type": "string"
},
"value": {
"description": "DEPRECATED. Please use one of the type-specific parameters."
},
"valueType": {
"description": "The valueType of the field. Use with the corresponding {type of field}Value attribute. Signature and photo fields do not support values added via API. Their values must be omitted or set to null. For example:\n\n```\n\n\"fields\": [\n\n {\n\n \"label\": \"Signature\",\n\n \"valueType\": \"ValueType_Signature\"\n\n },\n\n ... more fields\n\n]\n\n```",
"type": "string"
}
}
},
"example": [
{
"label": "Example number field label",
"numberValue": 999,
"valueType": "ValueType_Number"
},
{
"label": "text",
"stringValue": "example string",
"valueType": "ValueType_String"
},
{
"label": "Example multi choice label",
"multipleChoiceValue": [
{
"selected": false,
"value": "option 1"
},
{
"selected": true,
"value": "option 2"
}
],
"valueType": "ValueType_MultipleChoice"
},
{
"dateTimeValue": {
"dateTimeMs": 10855639004823
},
"label": "Example date time label",
"valueType": "ValueType_DateTime"
},
{
"label": "Example photo label",
"valueType": "ValueType_Photo"
},
{
"label": "Example signature label",
"valueType": "ValueType_Signature"
}
]
},
"DocumentFetchField": {
"type": "object",
"properties": {
"dateTimeValue": {
"description": "The value of a `ValueType_DateTime` field.",
"type": "object",
"required": [
"dateTimeMs"
],
"properties": {
"dateTimeMs": {
"description": "The Unix epoch on milliseconds of this date time field.",
"type": "integer",
"format": "int64",
"example": 10855639004823
}
}
},
"label": {
"description": "The name of the field.",
"type": "string"
},
"multipleChoiceValue": {
"description": "The value of a `ValueType_MultipleChoice` field.",
"type": "array",
"items": {
"type": "object",
"properties": {
"selected": {
"description": "Whether the multiple choice field is selected or not.",
"type": "boolean"
},
"value": {
"description": "The name of the multiple choice field.",
"type": "string"
}
}
}
},
"numberValue": {
"description": "The value of a `ValueType_Number` field.",
"type": "number",
"format": "double"
},
"photoValue": {
"description": "The value of a `ValueType_Photo` field.",
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"description": "A pre-signed URL to the selected photos that refreshes every 24 hours.",
"type": "string",
"example": "https://samsara-driver-media-upload.s3.us-west-2.amazonaws.com/123456"
}
}
}
},
"signatureValue": {
"description": "The value of a `ValueType_Signature` field.",
"type": "object",
"properties": {
"name": {
"description": "The name typed by the user when the signature was captured.",
"type": "string",
"example": "Samsara Owl"
},
"signedAtMs": {
"description": "The timestamp when the signature was captured.",
"type": "integer",
"format": "int64",
"example": 1584816363025
},
"url": {
"description": "A pre-signed URL to the captured signature PNG that refreshes every 24 hours.",
"type": "string",
"example": "https://samsara-driver-media-upload.s3.us-west-2.amazonaws.com/123456"
}
}
},
"stringValue": {
"description": "The value of a `ValueType_String` field.",
"type": "string"
},
"value": {
"description": "The value of a field. Type varies by field type."
},
"valueType": {
"description": "The type of this field.\nValid values: `ValueType_Number`, `ValueType_String`, `ValueType_Photo`, `ValueType_MultipleChoice`, `ValueType_Signature`, `ValueType_DateTime`.\nWhen creating documents via API, only `ValueType_Number`, `ValueType_String`, `ValueType_MultipleChoice`, and `ValueType_DateTime` are accepted.",
"type": "string"
}
}
},
"DocumentFetchFields": {
"type": "array",
"items": {
"$ref": "#/definitions/DocumentFetchField"
},
"example": [
{
"label": "Name of the number field",
"numberValue": 123,
"value": 123,
"valueType": "ValueType_Number"
},
{
"label": "Name of the string field",
"stringValue": "Example text value",
"value": "Example text value",
"valueType": "ValueType_String"
},
{
"label": "Name of the photo field",
"photoValue": [
{
"url": "https://samsara-driver-media-upload.s3.us-west-2.amazonaws.com/123456"
}
],
"value": [
{
"url": "https://samsara-driver-media-upload.s3.us-west-2.amazonaws.com/123456",
"uuid": "f5271458-21f9-4a9f-a290-780c6d8840ff"
}
],
"valueType": "ValueType_Photo"
},
{
"label": "Name of the multiple choice field",
"multipleChoiceValue": [
{
"selected": false,
"value": "option 1"
},
{
"selected": true,
"value": "option 2"
}
],
"value": [
{
"selected": false,
"value": "option 1"
},
{
"selected": true,
"value": "option 2"
}
],
"valueType": "ValueType_MultipleChoice"
},
{
"dateTimeValue": {
"dateTimeMs": 1596681182972
},
"label": "Name of the date time field",
"value": {
"dateTimeMs": 1596681182972
},
"valueType": "ValueType_DateTime"
},
{
"label": "Name of the signature field",
"signatureValue": {
"name": "John Smith",
"signedAtMs": 1596681191327,
"url": "https://samsara-driver-media-upload.s3.us-west-2.amazonaws.com/123456"
},
"value": {
"name": "John Smith",
"signedAtMs": 1596681191327,
"url": "https://samsara-driver-media-upload.s3.us-west-2.amazonaws.com/123456",
"uuid": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7"
},
"valueType": "ValueType_Signature"
}
]
},
"DocumentFieldType": {
"type": "object",
"required": [
"label",
"valueType"
],
"properties": {
"label": {
"description": "Name of this field type.",
"type": "string",
"example": "Fuel Cost ($)"
},
"multipleChoiceValueTypeMetadata": {
"description": "Metadata about the multiple choice value. Only present for value type `ValueType_MultipleChoice`.",
"type": "object",
"properties": {
"multipleChoiceOptionLabels": {
"description": "The labels for the multiple choice options.",
"type": "object",
"properties": {
"label": {
"description": "The lable for the multiple choice option",
"type": "string",
"example": "Loaded"
}
}
}
}
},
"numberValueTypeMetadata": {
"description": "Metadata about the numeric value type. Only present for value type `ValueType_Number`.",
"type": "object",
"properties": {
"numDecimalPlaces": {
"description": "The number of decimal places this value type can have.",
"type": "number",
"format": "int64",
"example": 2
}
}
},
"signatureValueTypeMetadata": {
"description": "Metadata about the signature value type. Only present for value type `ValueType_Signature`.",
"type": "object",
"properties": {
"legalText": {
"description": "The legal text associated with this signature.",
"type": "string"
}
}
},
"valueType": {
"description": "The type of value this field can have.\nValid values: `ValueType_Number`, `ValueType_String`, `ValueType_Photo`, `ValueType_MultipleChoice`, `ValueType_Signature`, `ValueType_DateTime`, `ValueType_ScannedDocument`.",
"type": "string",
"example": "ValueType_Number"
}
}
},
"DocumentType": {
"type": "object",
"required": [
"orgId",
"uuid",
"fieldTypes"
],
"properties": {
"conditionalFieldSections": {
"description": "Describe sets of fields conditionally triggered by an option select field.",
"type": "array",
"items": {
"$ref": "#/definitions/DocumentConditionalFieldSection"
}
},
"fieldTypes": {
"description": "The fields associated with this document type.",
"type": "array",
"items": {
"$ref": "#/definitions/DocumentFieldType"
}
},
"name": {
"description": "Name of the document type.",
"type": "string",
"example": "Fuel Receipt"
},
"orgId": {
"description": "ID for the organization this document belongs to.",
"type": "integer",
"format": "int64",
"example": 773
},
"uuid": {
"description": "Universally unique identifier for the document type. Can be passed in as the `documentTypeUuid` when creating a document for this document type.",
"type": "string",
"example": "4aff772c-a7bb-45e6-8e41-6a53e34feb83"
}
}
},
"DocumentTypes": {
"type": "array",
"items": {
"$ref": "#/definitions/DocumentType"
}
},
"Documents": {
"description": "List of documents.",
"type": "object",
"properties": {
"driverDocuments": {
"description": "List of documents.",
"type": "array",
"items": {
"$ref": "#/definitions/Document"
}
}
}
},
"DoorResponse": {
"description": "Contains the current door status of a sensor.",
"type": "object",
"properties": {
"groupId": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 101
},
"sensors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"doorClosed": {
"description": "Flag indicating whether the current door is closed or open.",
"type": "boolean",
"example": true
},
"doorStatusTime": {
"description": "The timestamp of reported door status, specified in RFC 3339 time.",
"type": "string",
"example": "2019-04-17T16:42:55Z"
},
"id": {
"description": "ID of the sensor.",
"type": "integer",
"format": "int64",
"example": 122
},
"name": {
"description": "Name of the sensor.",
"type": "string",
"example": "Trailer Door Sensor"
},
"trailerId": {
"description": "ID of the trailer associated with the sensor for the data point. If no trailer is connected, this parameter will not be reported.",
"type": "integer",
"example": 123
},
"vehicleId": {
"description": "ID of the vehicle associated with the sensor for the data point. If no vehicle is connected, this parameter will not be reported.",
"type": "integer",
"example": 124
}
}
}
}
}
},
"Driver": {
"allOf": [
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "ID of the driver.",
"type": "integer",
"format": "int64",
"example": 556
},
"isDeactivated": {
"description": "True if the driver account has been deactivated.",
"type": "boolean"
},
"tags": {
"type": "array",
"items": {
"$ref": "#/definitions/TagMetadata"
}
}
}
},
{
"type": "object",
"properties": {
"currentVehicleId": {
"description": "ID of the vehicle that this driver is currently assigned to. Omitted if there is no current vehicle assignment for this driver.",
"type": "integer",
"format": "int64",
"example": 879
}
}
},
{
"$ref": "#/definitions/DriverBase"
}
]
},
"DriverBase": {
"type": "object",
"required": [
"name"
],
"properties": {
"eldAdverseWeatherExemptionEnabled": {
"description": "Flag indicating this driver may use Adverse Weather exemptions in ELD logs.",
"type": "boolean"
},
"eldBigDayExemptionEnabled": {
"description": "Flag indicating this driver may use Big Day excemptions in ELD logs.",
"type": "boolean"
},
"eldDayStartHour": {
"description": "0 indicating midnight-to-midnight ELD driving hours, 12 to indicate noon-to-noon driving hours.",
"type": "integer"
},
"eldExempt": {
"description": "Flag indicating this driver is exempt from the Electronic Logging Mandate.",
"type": "boolean"
},
"eldExemptReason": {
"description": "Reason that this driver is exempt from the Electronic Logging Mandate (see eldExempt).",
"type": "string"
},
"eldPcEnabled": {
"description": "Flag indicating this driver may select the Personal Conveyance duty status in ELD logs.",
"type": "boolean",
"default": false
},
"eldYmEnabled": {
"description": "Flag indicating this driver may select the Yard Move duty status in ELD logs.",
"type": "boolean",
"default": false
},
"externalIds": {
"$ref": "#/definitions/ExternalIDs"
},
"groupId": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 101
},
"licenseNumber": {
"description": "Driver's state issued license number.",
"type": "string",
"example": "E1234567"
},
"licenseState": {
"description": "Abbreviation of state that issued driver's license.",
"type": "string",
"example": "CA"
},
"name": {
"description": "Driver's name.",
"type": "string",
"example": "Susan Jones"
},
"notes": {
"description": "Notes about the driver.",
"type": "string",
"example": "Also goes by the nickname 'Furious Fred'."
},
"phone": {
"description": "Driver's phone number. Please include only digits, ex. 4157771234",
"type": "string",
"example": "5558234327"
},
"timezone": {
"description": "Home terminal timezone, in order to indicate what time zone should be used to calculate the ELD logs. Driver timezones use [IANA timezone database](https://www.iana.org/time-zones) 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](https://unicode.org/cldr/charts/latest/supplemental/zone_tzid.html).",
"type": "string",
"example": "America/Los_Angeles"
},
"username": {
"description": "Driver's login username into the driver app. The username may not contain spaces or `@`.",
"type": "string",
"example": "SusanJones"
},
"vehicleGroupTagId": {
"description": "ID of the tag which determines which vehicles a driver will see when selecting vehicles",
"type": "integer",
"format": "int64",
"example": 171
},
"vehicleId": {
"description": "ID of the vehicle assigned to the driver for static vehicle assignments. (uncommon).",
"type": "integer",
"format": "int64",
"example": 444
}
}
},
"DriverDailyLogResponse": {
"type": "object",
"properties": {
"days": {
"type": "array",
"items": {
"type": "object",
"properties": {
"activeHours": {
"description": "Hours spent on duty or driving, rounded to two decimal places.",
"type": "number",
"format": "double",
"example": 5.4
},
"activeMs": {
"description": "Milliseconds spent on duty or driving.",
"type": "integer",
"format": "int64",
"example": 691200
},
"certified": {
"description": "Whether this HOS day chart was certified by the driver.",
"type": "boolean"
},
"certifiedAtMs": {
"description": "Unix epoch time (in ms) of time when this chart was certified. If this chart is uncertified, 0.",
"type": "number",
"format": "int64"
},
"distanceMiles": {
"description": "Distance driven in miles, rounded to two decimal places.",
"type": "number",
"format": "double",
"example": 123.24
},
"driveMs": {
"description": "Milliseconds spent driving. This is present for either certified or uncertified logs.",
"type": "integer",
"format": "int64",
"example": 12600000
},
"endMs": {
"description": "End of the HOS day, specified in milliseconds UNIX time.",
"type": "integer",
"example": 1473836400000
},
"onDutyMs": {
"description": "Milliseconds spent on duty. This is present for either certified or uncertified logs.",
"type": "integer",
"format": "int64",
"example": 21600000
},
"pendingDriveMs": {
"description": "Milliseconds spent driving based on pending carrier edits. If there are no pending carrier edits, this is equal to `driveMs`.",
"type": "integer",
"format": "int64",
"example": 12600000
},
"pendingOnDutyMs": {
"description": "Milliseconds spent on duty based on pending carrier edits. If there are no pending carrier edits, this is equal to `onDutyMs`.",
"type": "integer",
"format": "int64",
"example": 21600000
},
"shippingDocIds": {
"description": "List of customer shipping document IDs associated with the driver for the day.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"14334",
"Shipping Document ID 1"
]
},
"startMs": {
"description": "Start of the HOS day, specified in milliseconds UNIX time.",
"type": "integer",
"example": 1473750000000
},
"trailerIds": {
"description": "List of trailer ID's associated with the driver for the day.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"10293",
"Trailer ID 1"
]
},
"vehicleIds": {
"description": "List of vehicle ID's associated with the driver for the day.",
"type": "object",
"format": "int64",
"example": [
192319,
12958
]
}
}
}
}
}
},
"DriverForCreate": {
"allOf": [
{
"type": "object",
"required": [
"password"
],
"properties": {
"password": {
"description": "Driver's password for the driver app.",
"type": "string",
"example": "mypassword"
},
"tagIds": {
"$ref": "#/definitions/TagIds"
}
}
},
{
"$ref": "#/definitions/DriverBase"
}
]
},
"DriverForUpdate": {
"allOf": [
{
"type": "object",
"properties": {
"tagIds": {
"$ref": "#/definitions/TagIds"
}
}
},
{
"$ref": "#/definitions/DriverBase"
}
]
},
"DriverSafetyScoreResponse": {
"description": "Safety score details for a driver",
"type": "object",
"properties": {
"crashCount": {
"description": "Crash event count",
"type": "integer",
"example": 0
},
"driverId": {
"description": "Driver ID",
"type": "integer",
"example": 1234
},
"harshAccelCount": {
"description": "Harsh acceleration event count",
"type": "integer",
"example": 1
},
"harshBrakingCount": {
"description": "Harsh braking event count",
"type": "integer",
"example": 2
},
"harshEvents": {
"type": "array",
"items": {
"$ref": "#/definitions/SafetyReportHarshEvent"
}
},
"harshTurningCount": {
"description": "Harsh turning event count",
"type": "integer",
"example": 0
},
"safetyScore": {
"description": "Safety Score",
"type": "integer",
"example": 97
},
"safetyScoreRank": {
"description": "Safety Score Rank",
"type": "string",
"example": "26"
},
"timeOverSpeedLimitMs": {
"description": "Amount of time driven over the speed limit in milliseconds",
"type": "integer",
"example": 3769
},
"totalDistanceDrivenMeters": {
"description": "Total distance driven in meters",
"type": "integer",
"example": 291836
},
"totalHarshEventCount": {
"description": "Total harsh event count",
"type": "integer",
"example": 3
},
"totalTimeDrivenMs": {
"description": "Amount of time driven in milliseconds",
"type": "integer",
"example": 19708293
}
}
},
"DriversResponse": {
"type": "object",
"properties": {
"drivers": {
"type": "array",
"items": {
"$ref": "#/definitions/Driver"
}
}
}
},
"DriversSummaryResponse": {
"type": "object",
"properties": {
"Summaries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"activeMs": {
"description": "Duration in milliseconds that driver was on duty or driving during the requested time range. Yard moves are not included.",
"type": "number",
"format": "int64",
"example": 43200000
},
"distanceMiles": {
"description": "Distance driven in miles, rounded to two decimal places.",
"type": "number",
"format": "double",
"example": 123.24
},
"driveMs": {
"description": "Duration in milliseconds that driver was driving during the requested time range",
"type": "number",
"format": "int64",
"example": 21600000
},
"driverId": {
"description": "ID of the driver.",
"type": "integer",
"format": "int64",
"example": 444
},
"driverName": {
"description": "Name of the driver.",
"type": "string",
"example": "Fred Jacobs"
},
"driverUsername": {
"description": "Username of the driver.",
"type": "string",
"example": "fjacobs"
},
"groupId": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 111
},
"onDutyMs": {
"description": "Duration in milliseconds that driver was on duty during the requested time range",
"type": "number",
"format": "int64",
"example": 21600000
}
}
}
}
}
},
"DvirBase": {
"type": "object",
"properties": {
"authorSignature": {
"description": "The authors signature for the DVIR.",
"type": "object",
"properties": {
"driverId": {
"description": "ID of the driver who signed the DVIR. Will not be returned if mechanicUserId is returned.",
"type": "integer",
"format": "int64",
"example": 2581
},
"email": {
"description": "Email of the driver|mechanic who signed the DVIR.",
"type": "string",
"example": "j.smith@yahoo.com"
},
"mechanicUserId": {
"description": "ID of the mechanic who signed the DVIR. Will not be returned if driverId is returned.",
"type": "integer",
"format": "int64",
"example": 14849
},
"name": {
"description": "The name of the driver or mechanic who signed the DVIR.",
"type": "string",
"example": "John Smith"
},
"signedAt": {
"description": "The time in millis when the DVIR was signed",
"type": "integer",
"format": "int64",
"example": 12535500000
},
"type": {
"description": "Type corresponds to whether the signature corresponds to driver|mechanic.",
"type": "string",
"example": "driver"
},
"username": {
"description": "Username of the driver|mechanic who signed the DVIR.",
"type": "string",
"example": "jsmith"
}
}
},
"defectsCorrected": {
"description": "Signifies if the defects on the vehicle corrected after the DVIR is done.",
"type": "boolean",
"example": true
},
"defectsNeedNotBeCorrected": {
"description": "Signifies if the defects on this vehicle can be ignored.",
"type": "boolean",
"example": false
},
"id": {
"description": "The id of this DVIR record.",
"type": "integer",
"format": "int64",
"example": 19
},
"inspectionType": {
"description": "Inspection type of the DVIR.",
"type": "string",
"example": "pre trip"
},
"mechanicNotes": {
"description": "The mechanics notes on the DVIR.",
"type": "string",
"example": "The vehicle is now safe."
},
"mechanicOrAgentSignature": {
"description": "The mechanic's or agent's signature for the DVIR.",
"type": "object",
"properties": {
"driverId": {
"description": "ID of the driver who signed the DVIR. Will not be returned if mechanicUserId is returned.",
"type": "integer",
"format": "int64",
"example": 2581
},
"email": {
"description": "Email of the agent|mechanic who signed the DVIR.",
"type": "string",
"example": "j.smith@yahoo.com"
},
"mechanicUserId": {
"description": "ID of the mechanic who signed the DVIR. Will not be returned if driverId is returned.",
"type": "integer",
"format": "int64",
"example": 14849
},
"name": {
"description": "The name of the agent or mechanic who signed the DVIR.",
"type": "string",
"example": "John Smith"
},
"signedAt": {
"description": "The time in millis when the DVIR was signed",
"type": "integer",
"format": "int64",
"example": 12535500000
},
"type": {
"description": "Type corresponds to whether the signature corresponds to driver|mechanic.",
"type": "string",
"example": "driver"
},
"username": {
"description": "Username of the agent|mechanic who signed the DVIR.",
"type": "string",
"example": "jsmith"
}
}
},
"nextDriverSignature": {
"description": "The next driver signature for the DVIR.",
"type": "object",
"properties": {
"driverId": {
"description": "ID of the driver who signed the DVIR",
"type": "integer",
"format": "int64",
"example": 2581
},
"email": {
"description": "Email of the driver who signed the next DVIR on this vehicle.",
"type": "string",
"example": "j.smith@yahoo.com"
},
"name": {
"description": "The name of the driver who signed the next DVIR on this vehicle.",
"type": "string",
"example": "John Smith"
},
"signedAt": {
"description": "The time in millis when the next driver signed the DVIR on this vehicle.",
"type": "integer",
"format": "int64",
"example": 12535500000
},
"type": {
"description": "Type corresponds to driver.",
"type": "string",
"example": "driver"
},
"username": {
"description": "Username of the driver who signed the next DVIR on this vehicle.",
"type": "string",
"example": "jsmith"
}
}
},
"odometerMiles": {
"description": "The odometer reading in miles for the vehicle when the DVIR was done.",
"type": "integer",
"format": "int64",
"example": 49912
},
"startedAtMs": {
"description": "Timestamp when driver began filling out this DVIR, in UNIX milliseconds.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"timeMs": {
"description": "Timestamp of when this DVIR was signed \u0026 completed, in UNIX milliseconds.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"trailerDefects": {
"description": "Defects registered for the trailer which was part of the DVIR.",
"type": "array",
"items": {
"$ref": "#/definitions/DvirDefectBase"
}
},
"trailerId": {
"description": "The id of the trailer which was part of the DVIR.",
"type": "integer",
"example": 19
},
"trailerName": {
"description": "The name of the trailer which was part of the DVIR.",
"type": "string",
"example": "Storer's Trailer 19"
},
"vehicle": {
"description": "The vehicle on which DVIR was done.",
"type": "object",
"properties": {
"id": {
"description": "The vehicle id on which DVIR was done.",
"type": "integer",
"format": "int64",
"example": 19
},
"name": {
"description": "The vehicle on which DVIR was done.",
"type": "string",
"example": "Storer's vehicle 19"
}
}
},
"vehicleCondition": {
"description": "The condition of vechile on which DVIR was done.",
"type": "string",
"example": "SATISFACTORY"
},
"vehicleDefects": {
"description": "Defects registered for the vehicle which was part of the DVIR.",
"type": "array",
"items": {
"$ref": "#/definitions/DvirDefectBase"
}
}
}
},
"DvirDefectBase": {
"type": "object",
"properties": {
"comment": {
"description": "The comment describing the type of DVIR defect.",
"type": "string",
"example": "Air Compressor not working"
},
"defectType": {
"description": "The type of DVIR defect. Possible values: [`AIR_COMPRESSOR`, `AIR_CONDITIONER`, `AIR_LINES`, `BATTERY`, `BELTS_HOSES`, `BRAKE_ACCESSORIES`, `BRAKE_CHECK`, `BRAKE_CONNECTIONS`, `BRAKES`, `CLUTCH`, `COUPLING_DEVICES`, `DEFROSTER_HEATER`, `DOORS`, `DRIVE_LINE`, `EMERGENCY_DOOR_AND_BUZZER`, `ENGINE`, `ENTRANCE_STEPS`, `EXHAUST`, `FIFTH_WHEEL`, `FIRST_AID_KIT`, `FLUID_LEVELS`, `FRAME_ASSEMBLY`, `FRONT_AXLE`, `FUEL_TANKS`, `HORN`, `INTERIOR_AND_FLOOR`, `LANDING_GEAR`, `LIGHTS`, `MIRRORS`, `MUFFLER`, `OIL_PRESSURE`, `OTHER`, `RADIATOR`, `REAR_END`, `REFLECTORS`, `ROOF`, `SAFETY_EQUIPMENT`, `STARTER`, `STEERING`, `STOP_ARM_CONTROL`, `STOP_ARM`, `SUSPENSION`, `TIRE_CHAINS`, `TIRES`, `TRANSMISSION`, `TRIP_RECORDER`, `WHEELS_RIMS`, `WINDOWS`, `WINDSHIELD_WIPERS`, `UNSET`]",
"type": "string",
"example": "AIR_COMPRESSOR"
},
"id": {
"description": "The id of this defect.",
"type": "integer",
"format": "int64",
"example": 18
},
"resolved": {
"description": "Signifies if this defect is resolved.",
"type": "boolean",
"example": true
},
"resolvedAt": {
"description": "Timestamp when this defect was resolved, in UNIX milliseconds. Will not be returned if the defect is unresolved.",
"type": "integer",
"format": "int64",
"example": 1453449599999
},
"resolvedByDriverId": {
"description": "ID of the driver who resolved this defect. Will not be returned if the defect is unresolved or resolvedByMechanicId is returned.",
"type": "integer",
"format": "int64",
"example": 2581
},
"resolvedByMechanicId": {
"description": "ID of the mechanic who resolved this defect. Will not be returned if the defect is unresolved or resolvedByDriverId is returned.",
"type": "integer",
"format": "int64",
"example": 14849
}
}
},
"DvirListResponse": {
"type": "object",
"properties": {
"dvirs": {
"type": "array",
"items": {
"$ref": "#/definitions/DvirBase"
}
}
}
},
"EngineState": {
"description": "The state of the vehicle over time. State can be Running, Off, or Idle.",
"type": "object",
"required": [
"timeMs",
"value"
],
"properties": {
"timeMs": {
"description": "Timestamp in Unix epoch milliseconds.",
"type": "number",
"format": "int64",
"example": 1546542978484
},
"value": {
"type": "string",
"enum": [
"Running",
"Off",
"Idle"
]
}
}
},
"ErrorResponse": {
"description": "Error message describing why the request failed.",
"type": "string"
},
"ExternalIDs": {
"description": "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.",
"type": "object",
"additionalProperties": {
"type": "string"
},
"example": {
"maintenanceId": "250020",
"payrollId": "ABFS18600"
}
},
"FleetVehicleLocation": {
"description": "Contains the location and speed of a vehicle at a particular time",
"type": "object",
"properties": {
"latitude": {
"description": "The latitude of the location in degrees.",
"type": "number",
"format": "double",
"example": 37.2
},
"location": {
"description": "The best effort (street,city,state) for the latitude and longitude.",
"type": "string",
"example": "525 York, San Francisco, CA"
},
"longitude": {
"description": "The longitude of the location in degrees.",
"type": "number",
"format": "double",
"example": -122.5
},
"speedMilesPerHour": {
"description": "The speed calculated from GPS that the asset was traveling at in miles per hour.",
"type": "number",
"format": "double",
"example": 35.2
},
"timeMs": {
"description": "Time in Unix milliseconds since epoch when the asset was at the location.",
"type": "number",
"format": "int64",
"example": 1535586471332
}
}
},
"FleetVehicleLocations": {
"type": "array",
"items": {
"$ref": "#/definitions/FleetVehicleLocation"
}
},
"FleetVehicleResponse": {
"description": "A vehicle object as returned for fleet/vehicle",
"type": "object",
"required": [
"Id",
"Name"
],
"properties": {
"ExternalIds": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"example": {
"maintenanceId": "ABFS18600"
}
},
"HarshAccelSetting": {
"description": "Harsh event detection setting.",
"type": "string",
"example": "Heavy"
},
"Id": {
"description": "ID of the vehicle.",
"type": "integer",
"format": "int64",
"example": 112
},
"Name": {
"description": "Name of the vehicle.",
"type": "string",
"example": "Truck A7"
},
"VehicleInfo": {
"type": "object",
"properties": {
"Make": {
"description": "Make of the vehicle.",
"type": "string",
"example": "Honda"
},
"Model": {
"description": "Model of the Vehicle.",
"type": "string",
"example": "Odyssey"
},
"Vin": {
"description": "Vehicle Identification Number.",
"type": "string",
"example": "1FUJA6BD31LJ09646"
},
"Year": {
"description": "Year of the vehicle.",
"type": "integer",
"format": "int64",
"example": 1997
}
}
}
}
},
"FleetVehiclesLocations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "ID of the vehicle.",
"type": "integer",
"format": "int64",
"example": 112
},
"locations": {
"$ref": "#/definitions/FleetVehicleLocations"
},
"name": {
"description": "Name of the vehicle.",
"type": "string",
"example": "Truck A7"
}
}
}
},
"HosAuthenticationLogsResponse": {
"type": "object",
"properties": {
"authenticationLogs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"actionType": {
"description": "The log type - one of 'signin' or 'signout'",
"type": "string",
"example": "signin"
},
"address": {
"description": "DEPRECATED: THIS FIELD MAY NOT BE POPULATED",
"type": "string",
"example": "THIS FIELD MAY NOT BE POPULATED"
},
"addressName": {
"description": "DEPRECATED: THIS FIELD MAY NOT BE POPULATED",
"type": "string",
"example": "THIS FIELD MAY NOT BE POPULATED"
},
"city": {
"description": "DEPRECATED: THIS FIELD MAY NOT BE POPULATED",
"type": "string",
"example": "THIS FIELD MAY NOT BE POPULATED"
},
"happenedAtMs": {
"description": "The time at which the event was recorded in UNIX milliseconds.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"state": {
"description": "DEPRECATED: THIS FIELD MAY NOT BE POPULATED",
"type": "string",
"example": "THIS FIELD MAY NOT BE POPULATED"
}
}
}
}
}
},
"HosLogsResponse": {
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"codriverIds": {
"type": "array",
"items": {
"description": "Ids of codrivers during any of the logged trips",
"type": "number",
"example": 445
}
},
"driverId": {
"description": "ID of the driver.",
"type": "integer",
"format": "int64",
"example": 444
},
"groupId": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 101
},
"hosStatusType": {
"description": "The Hours of Service status type. One of `OFF_DUTY`, `SLEEPER_BED`, `DRIVING`, `ON_DUTY`, `YARD_MOVE`, `PERSONAL_CONVEYANCE`.",
"type": "string",
"example": "OFF_DUTY"
},
"locCity": {
"description": "City in which the log was recorded.",
"type": "string",
"example": "Ahwatukee"
},
"locLat": {
"description": "Latitude at which the log was recorded.",
"type": "number",
"format": "float",
"example": 23.413702345
},
"locLng": {
"description": "Longitude at which the log was recorded.",
"type": "number",
"format": "float",
"example": -98.502888123
},
"locName": {
"description": "Name of location at which the log was recorded.",
"type": "string",
"example": "McLean Site A"
},
"locState": {
"description": "State in which the log was recorded.",
"type": "string",
"example": "Arizona"
},
"logStartMs": {
"description": "The time at which the log/HOS status started in UNIX milliseconds.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"remark": {
"description": "Remark associated with the log entry.",
"type": "string",
"example": "Lunch Break"
},
"vehicleId": {
"description": "ID of the vehicle.",
"type": "integer",
"format": "int64",
"example": 112
}
}
}
}
}
},
"HosLogsSummaryResponse": {
"type": "object",
"properties": {
"drivers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currentDutyStatusCode": {
"description": "The Hours of Service status type.",
"type": "string",
"enum": [
"AUTO_DUTY",
"DRIVING",
"OFF_DUTY",
"ON_DUTY",
"PERSONAL_CONVEYANCE",
"SLEEPER_BED",
"YARD_MOVE",
"WAITING_TIME"
],
"example": "OFF_DUTY"
},
"cycleRemaining": {
"description": "The amount of remaining cycle time (in ms).",
"type": "integer",
"format": "int64",
"example": 252000000
},
"cycleTomorrow": {
"description": "The amount of cycle time (in ms) available tomorrow.",
"type": "integer",
"format": "int64",
"example": 252000000
},
"driveMsToday": {
"description": "The amount of driving time today (in ms).",
"type": "number",
"format": "int64",
"example": 252000000
},
"driverId": {
"description": "ID of the driver.",
"type": "integer",
"format": "int64",
"example": 444
},
"driverName": {
"description": "Name of the driver.",
"type": "string",
"example": "Fred Jacobs"
},
"drivingInViolationCycle": {
"description": "The amount of driving time in violation in this cycle (in ms).",
"type": "integer",
"format": "int64",
"example": 50400000
},
"drivingInViolationToday": {
"description": "The amount of driving time in violation today (in ms).",
"type": "integer",
"format": "int64",
"example": 39600000
},
"onDutyMsToday": {
"description": "The amount of on duty time today (in ms).",
"type": "number",
"format": "int64",
"example": 252000000
},
"pendingDriveMsToday": {
"description": "The amount of driving time today for pending logs (in ms).",
"type": "number",
"format": "int64",
"example": 252000000
},
"pendingOnDutyMsToday": {
"description": "The amount of on duty time today for pending logs (in ms).",
"type": "number",
"format": "int64",
"example": 252000000
},
"shiftDriveRemaining": {
"description": "The amount of remaining shift drive time (in ms).",
"type": "integer",
"format": "int64",
"example": 39600000
},
"shiftRemaining": {
"description": "The amount of remaining shift time (in ms).",
"type": "integer",
"format": "int64",
"example": 50400000
},
"timeInCurrentStatus": {
"description": "The amount of time (in ms) that the driver has been in the current `dutyStatus`.",
"type": "integer",
"format": "int64",
"example": 5000
},
"timeUntilBreak": {
"description": "The amount of time (in ms) remaining until the driver cannot drive without a rest break.",
"type": "integer",
"format": "int64",
"example": 28800000
},
"vehicleName": {
"description": "Name of the vehicle.",
"type": "string",
"example": "Vehicle 1"
}
}
}
},
"pagination": {
"type": "object",
"required": [
"hasNextPage",
"endCursor"
],
"properties": {
"endCursor": {
"description": "Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter.",
"type": "string",
"example": "MTA1MDc5MB=="
},
"hasNextPage": {
"description": "True if there are more pages of results after this response.",
"type": "boolean"
}
}
}
}
},
"HumidityResponse": {
"description": "Contains the current humidity of a sensor.",
"type": "object",
"properties": {
"groupId": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 101
},
"sensors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"humidity": {
"description": "Currently reported relative humidity in percent, from 0-100.",
"type": "integer",
"example": 53
},
"humidityTime": {
"description": "The timestamp of reported relative humidity, specified in RFC 3339 time.",
"type": "string",
"example": "2019-04-17T16:42:55Z"
},
"id": {
"description": "ID of the sensor.",
"type": "integer",
"format": "int64",
"example": 122
},
"name": {
"description": "Name of the sensor.",
"type": "string",
"example": "Freezer Humidity Sensor"
},
"trailerId": {
"description": "ID of the trailer associated with the sensor for the data point. If no trailer is connected, this parameter will not be reported.",
"type": "integer",
"example": 123
},
"vehicleId": {
"description": "ID of the vehicle associated with the sensor for the data point. If no vehicle is connected, this parameter will not be reported.",
"type": "integer",
"example": 124
}
}
}
}
}
},
"Machine": {
"description": "Contains information about a machine.",
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "ID of the machine.",
"type": "integer",
"format": "int64",
"example": 123
},
"name": {
"description": "Name of the machine.",
"type": "string",
"example": "Freezer ABC"
},
"notes": {
"description": "Notes about the machine",
"type": "string",
"example": "This is in the left hallway behind the conveyor belt"
}
}
},
"MachineHistoryResponse": {
"description": "Contains the results for a machine history request",
"type": "object",
"properties": {
"machines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Machine ID",
"type": "integer",
"example": 1
},
"name": {
"description": "Machine name",
"type": "string",
"example": "1/3 HP Motor"
},
"vibrations": {
"description": "List of vibration datapoints, with timestamp and vibration measurement for x/y/z axis in mm/s",
"type": "array",
"items": {
"type": "object",
"properties": {
"X": {
"type": "number",
"format": "double",
"example": 0.01
},
"Y": {
"type": "number",
"format": "double",
"example": 1.23
},
"Z": {
"type": "number",
"format": "double",
"example": 2.55
},
"time": {
"type": "integer",
"format": "int64",
"example": 1453449599999
}
}
}
}
}
}
}
}
},
"Message": {
"type": "object",
"required": [
"driverId",
"text"
],
"properties": {
"driverId": {
"description": "ID of the driver for whom the message is sent to or sent by.",
"type": "integer",
"format": "int64",
"example": 555
},
"text": {
"description": "The text sent in the message.",
"type": "string",
"example": "This is a message."
}
}
},
"MessageResponse": {
"type": "object",
"required": [
"driverId",
"text",
"sentAtMs",
"sender",
"isRead"
],
"properties": {
"driverId": {
"description": "ID of the driver for whom the message is sent to or sent by.",
"type": "integer",
"format": "int64",
"example": 555
},
"isRead": {
"description": "True if the message was read by the recipient.",
"type": "boolean",
"example": true
},
"sender": {
"$ref": "#/definitions/MessageSender"
},
"sentAtMs": {
"description": "The time in Unix epoch milliseconds that the message is sent to the recipient.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"text": {
"description": "The text sent in the message.",
"type": "string",
"example": "This is a message."
}
}
},
"MessageSender": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"name": {
"description": "Name of user that is sending the message.",
"type": "string",
"example": "John Doe"
},
"type": {
"description": "Type of user that is sending the message. It will be either dispatch or driver.",
"type": "string",
"example": "dispatch"
}
}
},
"Messages": {
"type": "array",
"items": {
"$ref": "#/definitions/Message"
}
},
"MessagesResponse": {
"type": "array",
"items": {
"$ref": "#/definitions/MessageResponse"
}
},
"Pagination": {
"type": "object",
"required": [
"hasNextPage",
"hasPrevPage",
"startCursor",
"endCursor"
],
"properties": {
"endCursor": {
"description": "Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'startingAfter' query parameter.",
"type": "string",
"example": "MTU5MTEzNjA2OTU0MzQ3"
},
"hasNextPage": {
"description": "True if there are more pages of results after this response.",
"type": "boolean"
},
"hasPrevPage": {
"description": "True if there are more pages of results before this response.",
"type": "boolean"
},
"startCursor": {
"description": "Cursor identifier representing the first element in the response. This value should be used in conjunction with a subsequent request's 'ending_before' query parameter.",
"type": "string",
"example": "MTU5MTEzNjA2OTU0MzQ3"
}
}
},
"ProgramsForTheCameraResponse": {
"description": "Contains the list of Programs configured on the given Camera.",
"type": "array",
"items": {
"type": "object",
"properties": {
"programId": {
"type": "integer",
"format": "int64",
"example": 1
},
"programName": {
"type": "string",
"example": "Barcode verification program"
}
}
}
},
"SafetyReportHarshEvent": {
"description": "List of harsh events",
"type": "object",
"properties": {
"harshEventType": {
"description": "Type of the harsh event",
"type": "string",
"example": "Harsh Braking"
},
"timestampMs": {
"description": "Timestamp that the harsh event occurred in Unix milliseconds since epoch",
"type": "integer",
"example": 1535590776000
},
"vehicleId": {
"description": "Vehicle associated with the harsh event",
"type": "integer",
"example": 212014918086169
}
}
},
"Sensor": {
"description": "Contains information about a sensor.",
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "ID of the sensor.",
"type": "integer",
"format": "int64",
"example": 123
},
"macAddress": {
"description": "MAC address of the sensor.",
"type": "string",
"example": "11:11:11:11:11:11"
},
"name": {
"description": "Name of the sensor.",
"type": "string",
"example": "Freezer ABC"
}
}
},
"SensorHistoryResponse": {
"description": "Contains the results for a sensor history request. Each result contains a timestamp and datapoint for each requested (sensor, field) pair.",
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"series": {
"description": "List of datapoints, one for each requested (sensor, field) pair.",
"type": "array",
"items": {
"type": "integer",
"format": "int64",
"example": 1
}
},
"timeMs": {
"description": "Timestamp in UNIX milliseconds.",
"type": "integer",
"example": 1453449599999
}
}
}
}
}
},
"Tag": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"addresses": {
"description": "The addresses that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedAddress"
}
},
"assets": {
"description": "The assets that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedAsset"
}
},
"drivers": {
"description": "The drivers that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedDriver"
}
},
"groupId": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 2348
},
"id": {
"description": "The ID of this tag.",
"type": "integer",
"format": "int64",
"example": 12345
},
"machines": {
"description": "The machines that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedMachine"
}
},
"name": {
"description": "Name of this tag.",
"type": "string",
"example": "Broken Vehicles"
},
"parentTagId": {
"description": "If this tag is part a hierarchical tag tree as a child tag, the parentTagId is the ID of this tag's parent tag.",
"type": "integer",
"format": "int64",
"example": 8389
},
"sensors": {
"description": "The sensors that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedSensor"
}
},
"vehicles": {
"description": "The vehicles that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedVehicle"
}
}
}
},
"TagCreate": {
"type": "object",
"required": [
"name"
],
"properties": {
"assets": {
"description": "The assets that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedAssetBase"
}
},
"drivers": {
"description": "The drivers that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedDriverBase"
}
},
"machines": {
"description": "The machines that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedMachineBase"
}
},
"name": {
"description": "Name of this tag.",
"type": "string",
"example": "Broken Vehicles"
},
"parentTagId": {
"description": "If this tag is part a hierarchical tag tree as a child tag, the parentTagId is the ID of this tag's parent tag.",
"type": "integer",
"format": "int64",
"example": 8389
},
"sensors": {
"description": "The sensors that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedSensorBase"
}
},
"vehicles": {
"description": "The vehicles that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedVehicleBase"
}
}
}
},
"TagIds": {
"description": "A list of tag IDs.",
"type": "array",
"items": {
"type": "number",
"format": "int64",
"example": 123
}
},
"TagMetadata": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"description": "The ID of this tag.",
"type": "integer",
"format": "int64",
"example": 12345
},
"name": {
"description": "Name of this tag.",
"type": "string",
"example": "Broken Vehicles"
}
}
},
"TagModify": {
"type": "object",
"properties": {
"add": {
"description": "Specify devices, etc. that should be added to the tag.",
"type": "object",
"properties": {
"assets": {
"description": "The assets to be added to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedAssetBase"
}
},
"drivers": {
"description": "The drivers to be added to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedDriverBase"
}
},
"machines": {
"description": "The machines to be added to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedMachineBase"
}
},
"sensors": {
"description": "The sensors to be added to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedSensorBase"
}
},
"vehicles": {
"description": "The vehicles to be added to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedVehicleBase"
}
}
}
},
"delete": {
"description": "Specify devices, etc. that should be removed from the tag.",
"type": "object",
"properties": {
"assets": {
"description": "The assets to be removed from this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedAssetBase"
}
},
"drivers": {
"description": "The drivers to be removed from this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedDriverBase"
}
},
"machines": {
"description": "The machines to be removed from this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedMachineBase"
}
},
"sensors": {
"description": "The sensors to be removed from this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedSensorBase"
}
},
"vehicles": {
"description": "The vehicles to be removed from this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedVehicleBase"
}
}
}
},
"name": {
"description": "Updated name of this tag.",
"type": "string",
"example": "Broken Vehicles"
},
"parentTagId": {
"description": "If this tag is part a hierarchical tag tree as a child tag, the parentTagId is the ID of this tag's parent tag.",
"type": "integer",
"format": "int64",
"example": 8389
}
}
},
"TagUpdate": {
"type": "object",
"properties": {
"assets": {
"description": "The assets that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedAssetBase"
}
},
"drivers": {
"description": "The drivers that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedDriverBase"
}
},
"machines": {
"description": "The machines that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedMachineBase"
}
},
"name": {
"description": "Updated name of this tag.",
"type": "string",
"example": "Broken Vehicles"
},
"parentTagId": {
"description": "If this tag is part a hierarchical tag tree as a child tag, the parentTagId is the ID of this tag's parent tag.",
"type": "integer",
"format": "int64",
"example": 8389
},
"sensors": {
"description": "The sensors that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedSensorBase"
}
},
"vehicles": {
"description": "The vehicles that belong to this tag.",
"type": "array",
"items": {
"$ref": "#/definitions/TaggedVehicleBase"
}
}
}
},
"TaggedAddress": {
"allOf": [
{
"$ref": "#/definitions/TaggedAddressBase"
},
{
"type": "object",
"properties": {
"name": {
"description": "Name of the address being tagged.",
"type": "string",
"example": "Truck Lot 345"
}
}
}
]
},
"TaggedAddressBase": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "The ID of the address being tagged.",
"type": "integer",
"format": "int64",
"example": 345
}
}
},
"TaggedAsset": {
"allOf": [
{
"$ref": "#/definitions/TaggedAssetBase"
},
{
"type": "object",
"properties": {
"name": {
"description": "Name of the Asset being tagged.",
"type": "string",
"example": "Trailer 789"
}
}
}
]
},
"TaggedAssetBase": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "The ID of the Asset being tagged.",
"type": "integer",
"format": "int64",
"example": 789
}
}
},
"TaggedDriver": {
"allOf": [
{
"$ref": "#/definitions/TaggedDriverBase"
},
{
"type": "object",
"properties": {
"name": {
"description": "Name of the Driver being tagged.",
"type": "string",
"example": "John Smith"
}
}
}
]
},
"TaggedDriverBase": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "The ID of the Driver being tagged.",
"type": "integer",
"format": "int64",
"example": 456
}
}
},
"TaggedMachine": {
"allOf": [
{
"$ref": "#/definitions/TaggedMachineBase"
},
{
"type": "object",
"properties": {
"name": {
"description": "Name of the Machine being tagged.",
"type": "string",
"example": "Vibration Monitor 567"
}
}
}
]
},
"TaggedMachineBase": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "The ID of the Machine being tagged.",
"type": "integer",
"format": "int64",
"example": 567
}
}
},
"TaggedSensor": {
"allOf": [
{
"$ref": "#/definitions/TaggedSensorBase"
},
{
"type": "object",
"properties": {
"name": {
"description": "Name of the Sensor being tagged.",
"type": "string",
"example": "Temperature Sensor 345"
}
}
}
]
},
"TaggedSensorBase": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "The ID of the Sensor being tagged.",
"type": "integer",
"format": "int64",
"example": 345
}
}
},
"TaggedVehicle": {
"allOf": [
{
"$ref": "#/definitions/TaggedVehicleBase"
},
{
"type": "object",
"properties": {
"name": {
"description": "Name of the Vehicle being tagged.",
"type": "string",
"example": "Heavy Duty 123"
}
}
}
]
},
"TaggedVehicleBase": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "The ID of the Vehicle being tagged.",
"type": "integer",
"format": "int64",
"example": 123
}
}
},
"TemperatureResponse": {
"description": "Contains the current temperatures of a sensor.",
"type": "object",
"properties": {
"groupId": {
"description": "Deprecated.",
"type": "integer",
"format": "int64",
"example": 101
},
"sensors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ambientTemperature": {
"description": "Currently reported ambient temperature in millidegrees celsius.",
"type": "integer",
"example": 11057
},
"ambientTemperatureTime": {
"description": "The timestamp of reported ambient temperature, specified in RFC 3339 time.",
"type": "string",
"example": "2019-04-17T16:42:55Z"
},
"id": {
"description": "ID of the sensor.",
"type": "integer",
"format": "int64",
"example": 122
},
"name": {
"description": "Name of the sensor.",
"type": "string",
"example": "Freezer Temp Sensor"
},
"probeTemperature": {
"description": "Currently reported probe temperature in millidegrees celsius. If no probe is connected, this parameter will not be reported.",
"type": "integer",
"example": -20145
},
"probeTemperatureTime": {
"description": "The timestamp of reported probe temperature, specified in RFC 3339 time.",
"type": "string",
"example": "2019-04-17T16:42:55Z"
},
"trailerId": {
"description": "ID of the trailer associated with the sensor for the data point. If no trailer is connected, this parameter will not be reported.",
"type": "integer",
"example": 123
},
"vehicleId": {
"description": "ID of the vehicle associated with the sensor for the data point. If no vehicle is connected, this parameter will not be reported.",
"type": "integer",
"example": 124
}
}
}
}
}
},
"TrailerAssignmentResponse": {
"type": "object",
"properties": {
"driverId": {
"description": "The ID of the driver associated with this trailer.",
"type": "integer",
"format": "int64",
"example": 2047
},
"endMs": {
"description": "The time at which the driver ended the assignment. If the assignment is current, this value will be omitted.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"startMs": {
"description": "The time at which the driver started the assignment",
"type": "integer",
"format": "int64",
"example": 1462878398034
}
}
},
"TrailerAssignmentsResponse": {
"allOf": [
{
"$ref": "#/definitions/TrailerBase"
},
{
"type": "object",
"properties": {
"trailerAssignments": {
"type": "array",
"items": {
"$ref": "#/definitions/TrailerAssignmentResponse"
}
}
}
}
]
},
"TrailerBase": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"description": "ID of the trailer",
"type": "integer",
"format": "int64",
"example": 2041
},
"name": {
"description": "Assignment trailer name (given when creating trailer via the trailer portal)",
"type": "string",
"format": "string",
"example": "myTrailer"
}
}
},
"TripResponse": {
"description": "Contains the trips for the vehicle in the requested timeframe. A trip is represented as an object that contains startMs, startLocation, startAddress, startCoordinates, endMs, endLocation, endAddress and endCoordinates. Ongoing trips will be returned with 9223372036854775807 as their endMs.",
"type": "object",
"properties": {
"trips": {
"type": "array",
"items": {
"type": "object",
"properties": {
"assetIds": {
"description": "List of associated asset IDs",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"example": [
122
]
},
"codriverIds": {
"description": "List of codriver IDs",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"example": [
122
]
},
"distanceMeters": {
"description": "Length of the trip in meters. This value is calculated from the GPS data collected by the Samsara Vehicle Gateway.",
"type": "integer",
"example": 2500
},
"driverId": {
"description": "ID of the driver.",
"type": "integer",
"example": 719
},
"endAddress": {
"description": "Text representation of nearest identifiable location to the end (latitude, longitude) coordinates.",
"type": "object",
"properties": {
"address": {
"description": "The formatted address",
"type": "string",
"example": "123 Main St, Sunnyvale, CA 94089"
},
"id": {
"description": "The ID of the address",
"type": "number",
"format": "int64",
"example": 581
},
"name": {
"description": "The name of the address",
"type": "string",
"example": "Ramen Tatsunoya"
}
}
},
"endCoordinates": {
"description": "End (latitude, longitude) in decimal degrees.",
"type": "object",
"properties": {
"latitude": {
"type": "number",
"format": "double",
"example": 23.413702345
},
"longitude": {
"type": "number",
"format": "double",
"example": -91.502888123
}
}
},
"endLocation": {
"description": "Geocoded street address of end (latitude, longitude) coordinates. Returns coordinates if geocoding fails, such as (37.429207, -121.920006)",
"type": "string",
"example": "571 S Lake Ave, Pasadena, CA 91101"
},
"endMs": {
"description": "End of the trip in UNIX milliseconds. Ongoing trips are indicated by an endMs value of 9223372036854775807.",
"type": "integer",
"example": 1462881998034
},
"endOdometer": {
"description": "Odometer reading (in meters) at the end of the trip. This is read from the vehicle's on-board diagnostics. If Samsara cannot read the vehicle's odometer values from on-board diagnostics, this value will be 0.",
"type": "integer",
"example": 210430500
},
"fuelConsumedMl": {
"description": "Amount in milliliters of fuel consumed on this trip.",
"type": "integer",
"example": 75700
},
"startAddress": {
"description": "Text representation of nearest identifiable location to the start (latitude, longitude) coordinates.",
"type": "object",
"properties": {
"address": {
"description": "The formatted address",
"type": "string",
"example": "123 Main St, Sunnyvale, CA 94089"
},
"id": {
"description": "The ID of the address",
"type": "number",
"format": "int64",
"example": 581
},
"name": {
"description": "The name of the address",
"type": "string",
"example": "Ramen Tatsunoya"
}
}
},
"startCoordinates": {
"description": "Start (latitude, longitude) in decimal degrees.",
"type": "object",
"properties": {
"latitude": {
"type": "number",
"format": "double",
"example": 29.443702345
},
"longitude": {
"type": "number",
"format": "double",
"example": -98.502888123
}
}
},
"startLocation": {
"description": "Geocoded street address of start (latitude, longitude) coordinates. Returns coordinates if geocoding fails, such as (37.429207, -121.920006)",
"type": "string",
"example": "16 N Fair Oaks Ave, Pasadena, CA 91103"
},
"startMs": {
"description": "Beginning of the trip in UNIX milliseconds.",
"type": "integer",
"example": 1462878398034
},
"startOdometer": {
"description": "Odometer reading (in meters) at the beginning of the trip. This is read from the vehicle's on-board diagnostics. If Samsara cannot read the vehicle's odometer values from on-board diagnostics, this value will be 0.",
"type": "integer",
"example": 210430450
},
"tollMeters": {
"description": "Length in meters trip spent on toll roads.",
"type": "integer",
"example": 32000
}
}
}
}
}
},
"UpsertUserBase": {
"type": "object",
"properties": {
"authType": {
"description": "The authentication type the user uses to authenticate. To use SAML this organization must have a configured SAML integration.",
"type": "string",
"enum": [
"default",
"saml"
]
},
"name": {
"description": "The first and last name of the user.",
"type": "string",
"example": "Jane Doe"
},
"organizationRoleId": {
"description": "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.",
"type": "string",
"example": "23d4d8d3-dc10-4e7a-a183-69968751f23e"
},
"tagRoles": {
"description": "If specified, the user will be an administrator for these tags. If left blank, the user has access to the entire organization.",
"type": "array",
"items": {
"type": "object",
"properties": {
"roleId": {
"description": "The id of the role",
"type": "string",
"example": "8a9371af-82d1-4158-bf91-4ecc8d3a114c"
},
"tagId": {
"description": "The id of the tag to grant this user access to.",
"type": "number",
"format": "int64",
"example": "123"
}
}
}
}
}
},
"User": {
"allOf": [
{
"$ref": "#/definitions/UserBase"
},
{
"type": "object",
"properties": {
"id": {
"description": "The ID of the User record.",
"type": "integer",
"format": "int64",
"example": 123
},
"organizationRole": {
"description": "The name 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.",
"type": "string",
"example": "Full Admin"
},
"tagRoles": {
"description": "The specific tags this user has access to. This will be blank for users that have full access to the organization.",
"type": "array",
"items": {
"$ref": "#/definitions/UserTagRole"
}
}
}
}
]
},
"UserBase": {
"type": "object",
"required": [
"email",
"authType"
],
"properties": {
"authType": {
"description": "The authentication type the user uses to authenticate. To use SAML this organization must have a configured SAML integration.",
"type": "string",
"enum": [
"default",
"saml"
]
},
"email": {
"description": "The email address of this user.",
"type": "string",
"example": "user@company.com"
},
"name": {
"description": "The first and last name of the user.",
"type": "string",
"example": "Jane Doe"
},
"organizationRoleId": {
"description": "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.",
"type": "string",
"example": "23d4d8d3-dc10-4e7a-a183-69968751f23e"
}
}
},
"UserRole": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "8a9371af-82d1-4158-bf91-4ecc8d3a114c"
},
"name": {
"type": "string",
"example": "Full Admin"
}
}
},
"UserTagRole": {
"type": "object",
"required": [
"tag",
"roleId"
],
"properties": {
"role": {
"description": "The name of the role the user has been granted on this tag.",
"type": "string",
"example": "Full Admin"
},
"roleId": {
"description": "The id of the role the user has been granted on this tag.",
"type": "string",
"example": "8a9371af-82d1-4158-bf91-4ecc8d3a114c"
},
"tag": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"description": "The ID of this tag.",
"type": "integer",
"format": "int64",
"example": 12345
},
"name": {
"description": "Name of this tag.",
"type": "string",
"example": "North Carolina Distribution"
},
"parentTagId": {
"description": "The ID of this tag.",
"type": "integer",
"format": "int64",
"example": 12345
}
}
}
}
},
"Vehicle": {
"description": "A vehicle object.",
"type": "object",
"required": [
"id"
],
"properties": {
"engineHours": {
"description": "Total engine hours for the vehicle.",
"type": "integer",
"format": "int64",
"example": 1500
},
"fuelLevelPercent": {
"description": "The fuel level of the vehicle as a percentage. (0.0 to 1.0)",
"type": "number",
"format": "float64",
"example": 0.3
},
"id": {
"description": "ID of the vehicle.",
"type": "integer",
"format": "int64",
"example": 112
},
"name": {
"description": "Name of the vehicle.",
"type": "string",
"example": "Truck A7"
},
"note": {
"type": "string",
"example": "Red truck 2015 M16"
},
"odometerMeters": {
"description": "The number of meters reported by the odometer.",
"type": "integer",
"format": "int64",
"example": 60130000
},
"tags": {
"type": "array",
"items": {
"$ref": "#/definitions/TagMetadata"
},
"x-omitempty": true
},
"vin": {
"description": "Vehicle Identification Number.",
"type": "string",
"example": "1FUJA6BD31LJ09646"
}
}
},
"VehicleHarshEventResponse": {
"description": "Harsh event details for a vehicle",
"type": "object",
"required": [
"incidentReportUrl",
"harshEventType"
],
"properties": {
"downloadForwardVideoUrl": {
"description": "URL for downloading the forward facing video",
"type": "string",
"example": "https://samsara-dashcam-videos.s3.us-west-2.amazonaws.com/123/212123456789012/1539201872984/abC123De4-camera-video-segment-123456789.mp4?..."
},
"downloadInwardVideoUrl": {
"description": "URL for downloading the inward facing video",
"type": "string",
"example": "https://samsara-dashcam-videos.s3.us-west-2.amazonaws.com/123/212123456789012/1539201872984/abC123De4-camera-video-segment-driver-123456789.mp4?..."
},
"downloadTrackedInwardVideoUrl": {
"description": "URL for downloading the tracked inward facing video",
"type": "string",
"example": "https://samsara-dashcam-videos.s3.us-west-2.amazonaws.com/123/212123456789012/1539201872984/abC123De4-camera-video-segment-driver-123456789.tracked.mp4?..."
},
"harshEventType": {
"description": "Type of the harsh event. One of: [Crash, Harsh Acceleration, Harsh Braking, Harsh Turn, ROP Engine, ROP Brake, YC Engine, YC Brake, Harsh Event]",
"type": "string",
"example": "Harsh Braking"
},
"incidentReportUrl": {
"description": "URL of the associated incident report page",
"type": "string",
"example": "https://cloud.samsara.com/groups/1234/fleet/reports/safety/vehicle/212123456789012/incident/1539201882984"
},
"isDistracted": {
"description": "Whether the driver was deemed distracted during this harsh event",
"type": "boolean",
"example": true
},
"location": {
"type": "object",
"properties": {
"address": {
"description": "Address of location where the harsh event occurred",
"type": "string",
"example": "350 Rhode Island St, San Francisco, CA"
},
"latitude": {
"description": "Latitude of location where the harsh event occurred",
"type": "number",
"example": 33.07614328
},
"longitude": {
"description": "Longitude of location where the harsh event occurred",
"type": "number",
"example": -96.14907287
}
}
}
}
},
"VehicleLocation": {
"description": "Contains the location, in latitude and longitude, of a vehicle.",
"type": "object",
"required": [
"id"
],
"properties": {
"driverId": {
"description": "The ID of the driver currently assigned to this vehicle.",
"type": "integer",
"example": 1
},
"heading": {
"description": "Heading in degrees.",
"type": "number",
"format": "double",
"example": 246.42
},
"id": {
"description": "ID of the vehicle.",
"type": "integer",
"format": "int64",
"example": 112
},
"latitude": {
"description": "Latitude in decimal degrees.",
"type": "number",
"format": "double",
"example": 123.456
},
"location": {
"description": "Text representation of nearest identifiable location to (latitude, longitude) coordinates.",
"type": "string",
"example": "1 Main St, Dallas, TX"
},
"longitude": {
"description": "Longitude in decimal degrees.",
"type": "number",
"format": "double",
"example": 32.897
},
"name": {
"description": "Name of the vehicle.",
"type": "string",
"example": "Truck A7"
},
"odometerMeters": {
"description": "The number of meters reported by the odometer.",
"type": "integer",
"format": "int64",
"example": 71774705
},
"odometerType": {
"description": "The source of data for odometerMeters. Will be either GPS or OBD",
"type": "string",
"enum": [
"GPS",
"OBD"
],
"example": "GPS"
},
"onTrip": {
"description": "Whether or not a trip is currently in progress for this vehicle. More information available via /fleet/trips endpoint.",
"type": "boolean",
"example": true
},
"routeIds": {
"description": "A list of currently active route IDs that the vehicle is in.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"example": [
2244514,
2311654
]
},
"speed": {
"description": "Speed in miles per hour.",
"type": "number",
"format": "double",
"example": 64.37
},
"time": {
"description": "The time the reported location was logged, reported as a UNIX timestamp in milliseconds.",
"type": "integer",
"example": 1462881998034
},
"vin": {
"description": "Vehicle Identification Number (VIN) of the vehicle.",
"type": "string",
"example": "JTNBB46KX73011966"
}
}
},
"VehicleMaintenance": {
"description": "Contains any J1939/Passenger engine light warnings and engine faults.",
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "ID of the vehicle.",
"type": "integer",
"format": "int64",
"example": 112
},
"j1939": {
"description": "J1939 based data. Null if no data is available.",
"type": "object",
"properties": {
"checkEngineLight": {
"description": "J1939 check engine lights.",
"type": "object",
"properties": {
"emissionsIsOn": {
"type": "boolean"
},
"protectIsOn": {
"type": "boolean"
},
"stopIsOn": {
"type": "boolean"
},
"warningIsOn": {
"type": "boolean"
}
}
},
"diagnosticTroubleCodes": {
"description": "J1939 DTCs.",
"type": "array",
"items": {
"type": "object",
"required": [
"fmiId",
"fmiText",
"occurrenceCount",
"spnDescription",
"spnId",
"txId"
],
"properties": {
"fmiId": {
"type": "integer"
},
"fmiText": {
"type": "string"
},
"occurrenceCount": {
"type": "integer"
},
"spnDescription": {
"type": "string"
},
"spnId": {
"type": "integer"
},
"txId": {
"type": "integer"
}
}
}
}
}
},
"passenger": {
"description": "Passenger vehicle data. Null if no data is available.",
"type": "object",
"properties": {
"checkEngineLight": {
"description": "Passenger vehicle check engine light.",
"type": "object",
"properties": {
"isOn": {
"type": "boolean"
}
}
},
"diagnosticTroubleCodes": {
"description": "Passenger vehicle DTCs.",
"type": "array",
"items": {
"type": "object",
"required": [
"dtcId",
"dtcDescription",
"dtcShortCode"
],
"properties": {
"dtcDescription": {
"type": "string"
},
"dtcId": {
"type": "integer"
},
"dtcShortCode": {
"type": "string"
}
}
}
}
}
}
}
},
"VehicleSafetyScoreResponse": {
"description": "Safety score details for a vehicle",
"type": "object",
"properties": {
"crashCount": {
"description": "Crash event count",
"type": "integer",
"example": 0
},
"harshAccelCount": {
"description": "Harsh acceleration event count",
"type": "integer",
"example": 1
},
"harshBrakingCount": {
"description": "Harsh braking event count",
"type": "integer",
"example": 2
},
"harshEvents": {
"type": "array",
"items": {
"$ref": "#/definitions/SafetyReportHarshEvent"
}
},
"harshTurningCount": {
"description": "Harsh turning event count",
"type": "integer",
"example": 0
},
"safetyScore": {
"description": "Safety Score",
"type": "integer",
"example": 97
},
"safetyScoreRank": {
"description": "Safety Score Rank",
"type": "string",
"example": "26"
},
"timeOverSpeedLimitMs": {
"description": "Amount of time driven over the speed limit in milliseconds",
"type": "integer",
"example": 3769
},
"totalDistanceDrivenMeters": {
"description": "Total distance driven in meters",
"type": "integer",
"example": 291836
},
"totalHarshEventCount": {
"description": "Total harsh event count",
"type": "integer",
"example": 3
},
"totalTimeDrivenMs": {
"description": "Amount of time driven in milliseconds",
"type": "integer",
"example": 19708293
},
"vehicleId": {
"description": "Vehicle ID",
"type": "integer",
"example": 4321
}
}
},
"VisionCamerasResponse": {
"description": "Contains the list of Cameras installed in the org.",
"type": "array",
"items": {
"type": "object",
"properties": {
"cameraId": {
"type": "integer",
"format": "int64",
"example": 1234512345999
},
"cameraName": {
"type": "string",
"example": "Line 32"
},
"ethernetIp": {
"type": "string",
"example": "10.1.2.34"
},
"wifiIp": {
"type": "string",
"example": "10.1.2.35"
}
}
}
},
"VisionRunByCameraResponse": {
"type": "object",
"properties": {
"cameraId": {
"type": "integer",
"format": "int64",
"example": 1234512345123
},
"endedAtMs": {
"type": "integer",
"format": "int64",
"example": 0
},
"inspectionResults": {
"type": "array",
"items": {
"type": "object",
"properties": {
"captureAtMs": {
"type": "number",
"format": "float64",
"example": 1553811994730
},
"result": {
"type": "string",
"example": "PASS"
},
"stepResults": {
"$ref": "#/definitions/VisionStepResults"
}
}
}
},
"isOngoing": {
"type": "boolean",
"example": true
},
"program": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1
},
"name": {
"type": "string",
"example": "Barcode verification program"
}
}
},
"runSummary": {
"type": "object",
"properties": {
"itemsPerMinute": {
"type": "number",
"format": "float64",
"example": 0.1
},
"noReadCount": {
"type": "integer",
"format": "int64",
"example": 0
},
"rejectCount": {
"type": "integer",
"format": "int64",
"example": 0
},
"successCount": {
"type": "integer",
"format": "int64",
"example": 181
}
}
},
"startedAtMs": {
"type": "integer",
"format": "int64",
"example": 1553808606097
}
}
},
"VisionRunsByCameraAndProgramResponse": {
"type": "object",
"properties": {
"deviceId": {
"type": "integer",
"format": "int64",
"example": 1234512345123
},
"endedAtMs": {
"type": "integer",
"format": "int64",
"example": 0
},
"programId": {
"type": "integer",
"format": "int64",
"example": 1
},
"reportMetadata": {
"type": "object",
"properties": {
"itemsPerMinute": {
"type": "number",
"format": "float64",
"example": 0.1
},
"noReadCount": {
"type": "integer",
"format": "int64",
"example": 0
},
"rejectCount": {
"type": "integer",
"format": "int64",
"example": 0
},
"successCount": {
"type": "integer",
"format": "int64",
"example": 181
}
}
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"captureAtMs": {
"type": "number",
"format": "float64",
"example": 1553811994730
},
"image": {
"type": "object",
"properties": {
"expiresAtMs": {
"type": "number",
"format": "int64",
"example": 1553812994730
},
"imageUrl": {
"type": "string",
"example": "https://samsara-machinevision-images.com/abc.jpg"
}
}
},
"result": {
"type": "string",
"example": "PASS"
},
"stepResults": {
"$ref": "#/definitions/VisionStepResults"
}
}
}
},
"startedAtMs": {
"type": "integer",
"format": "int64",
"example": 1553808606097
}
}
},
"VisionRunsByCameraResponse": {
"type": "array",
"items": {
"type": "object",
"properties": {
"deviceId": {
"type": "integer",
"format": "int64",
"example": 1234512345123
},
"endedAtMs": {
"type": "integer",
"format": "int64",
"example": 0
},
"program": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1
},
"name": {
"type": "string",
"example": "Barcode verification program"
}
}
},
"reportMetadata": {
"type": "object",
"properties": {
"itemsPerMinute": {
"type": "number",
"format": "float64",
"example": 0.1
},
"noReadCount": {
"type": "integer",
"format": "int64",
"example": 0
},
"rejectCount": {
"type": "integer",
"format": "int64",
"example": 0
},
"successCount": {
"type": "integer",
"format": "int64",
"example": 181
}
}
},
"startedAtMs": {
"type": "integer",
"format": "int64",
"example": 1553808606097
}
}
}
},
"VisionRunsResponse": {
"type": "object",
"properties": {
"visionRuns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"deviceId": {
"type": "integer",
"format": "int64",
"example": 1234512345123
},
"endedAtMs": {
"type": "integer",
"format": "int64",
"example": 0
},
"programId": {
"type": "integer",
"format": "int64",
"example": 1
},
"reportMetadata": {
"description": "The response includes 4 additional fields that are now deprecated",
"type": "object",
"properties": {
"itemsPerMinute": {
"description": "Returns average scanned items per minute. Should be used instead of scanRate.",
"type": "number",
"format": "float64",
"example": 0.1
},
"noReadCount": {
"description": "Returns no read count for the run. Should be used instead of noReadScansCount",
"type": "integer",
"format": "int64",
"example": 181
},
"rejectCount": {
"description": "Returns reject count for the run. Should be used instead of failedScansCount",
"type": "integer",
"format": "int64",
"example": 0
},
"successCount": {
"description": "Returns success count for the run. Should be used instead of successfulScansCount",
"type": "integer",
"format": "int64",
"example": 181
}
}
},
"startedAtMs": {
"type": "integer",
"format": "int64",
"example": 1553808606097
}
}
}
}
}
},
"VisionStepResults": {
"type": "array",
"items": {
"type": "object",
"properties": {
"angleCheck": {
"type": "object",
"properties": {
"angleConfigured": {
"description": "The configured angle allowance range (in degrees)",
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 150
},
"low": {
"type": "integer",
"format": "int64",
"example": 90
}
}
},
"angleFound": {
"description": "The counter-clockwise angle detected from the first edge to the second edge",
"type": "integer",
"format": "int64",
"example": 60
},
"endStepName": {
"description": "The name of the second reference step used to check the angle",
"type": "string",
"example": "Edge 2"
},
"startStepName": {
"description": "The name of the first reference step used to check the angle",
"type": "string",
"example": "Edge 1"
}
}
},
"barcode": {
"type": "array",
"items": {
"type": "object",
"properties": {
"contents": {
"type": "string",
"example": "10855639004823"
},
"matchString": {
"type": "string",
"example": "10855639004823"
},
"type": {
"type": "string",
"example": "EAN8"
}
}
}
},
"booleanLogic": {
"type": "object",
"properties": {
"operator": {
"type": "string",
"example": "AND"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Expiration Date"
},
"result": {
"type": "string",
"example": "PASS"
}
}
}
}
}
},
"caliper": {
"type": "object",
"properties": {
"angleRange": {
"description": "The configured angle allowance range",
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int32",
"example": 360
},
"low": {
"type": "integer",
"format": "int32",
"example": 0
}
}
},
"contrastRange": {
"description": "The configured contrast allowance range",
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 100
},
"low": {
"type": "integer",
"format": "int64",
"example": 50
}
}
},
"distanceFound": {
"description": "The distance found between the found edges",
"type": "number",
"format": "float",
"example": 555.55
},
"enforceAngleRange": {
"description": "Whether the edge should be filtered by angle (°).",
"type": "boolean",
"example": true
},
"enforceStraightnessRange": {
"description": "Whether the edge should be filtered by straightness (%).",
"type": "boolean",
"example": true
},
"filterPolarity": {
"description": "The configured polarity for finding edges",
"type": "string",
"default": "LIGHT TO DARK",
"enum": [
"LIGHT TO DARK",
"DARK TO LIGHT"
],
"example": "LIGHT TO DARK"
},
"maxDistance": {
"description": "The maximum allowed distance threshold",
"type": "number",
"format": "float",
"example": 1000
},
"minDistance": {
"description": "The minumum allowed distance threshold",
"type": "number",
"format": "float",
"example": 500
},
"sharpnessRange": {
"description": "The configured sharpness allowance range",
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 100
},
"low": {
"type": "integer",
"format": "int64",
"example": 80
}
}
},
"straightnessRange": {
"description": "The configured straightness allowance range",
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int32",
"example": 100
},
"low": {
"type": "integer",
"format": "int32",
"example": 80
}
}
},
"unit": {
"description": "The measurement unit of the distance found and the min and max distance threshold",
"type": "string",
"example": "Millimeters"
}
}
},
"contour": {
"type": "object",
"properties": {
"angleDegrees": {
"description": "The rotation angle found",
"type": "integer",
"format": "int64",
"example": 0
},
"angleTolerance": {
"description": "The rotation angle allowance",
"type": "integer",
"format": "int64",
"example": 50
},
"matchPercentage": {
"description": "The contour match percentage with the configured contour",
"type": "integer",
"format": "int64",
"example": 46
},
"matchThreshold": {
"description": "The configured match threshold for contours",
"type": "integer",
"format": "int64",
"example": 18
}
}
},
"distance": {
"type": "object",
"properties": {
"distanceFound": {
"description": "The distance found between the start and end references",
"type": "integer",
"format": "float64",
"example": 1000.22
},
"endStepName": {
"description": "The name of the second reference step that we're checking the distances between",
"type": "string",
"example": "Bottom Right Square"
},
"enforceOffsetAngleRange": {
"description": "Whether an offset angle range is enforced",
"type": "boolean",
"example": true
},
"maxDistance": {
"description": "The maximum allowed distance threshold",
"type": "integer",
"format": "float64",
"example": 900
},
"maxOffsetAngle": {
"description": "The maximum angle allowance (in degrees) if enforceOffsetAngleRange is true",
"type": "integer",
"format": "int64",
"example": 90
},
"minDistance": {
"description": "The miniumum allowed distance threshold",
"type": "integer",
"format": "float64",
"example": 1500
},
"minOffsetAngle": {
"description": "The minimum angle allowance (in degrees) if enforceOffsetAngleRange is true",
"type": "integer",
"format": "int64",
"example": 45
},
"offsetAngleFound": {
"description": "The counter-clockwise angle (in degrees) found between the horizontal axis of the start reference step and the last",
"type": "integer",
"format": "int64",
"example": 50
},
"startStepName": {
"description": "The name of the first reference step that we're checking the distances between",
"type": "string",
"example": "Top Left Square"
},
"unit": {
"description": "The measurement unit of the distance found and the min and max distance threshold",
"type": "string",
"example": "Millimeters"
}
}
},
"expirationDate": {
"type": "object",
"properties": {
"dateOffset": {
"type": "integer",
"format": "int64",
"example": 1
},
"foundDate": {
"type": "string",
"example": "06/13/2019"
},
"matchDate": {
"type": "string",
"example": "06/13/2019"
}
}
},
"findCopies": {
"type": "object",
"properties": {
"angleTolerance": {
"description": "The orientation angle tolerance (+/- °)",
"type": "integer",
"format": "int64",
"example": 10
},
"foundCount": {
"description": "The number of copies found",
"type": "integer",
"format": "int64",
"example": 1
},
"maxCount": {
"description": "The maximum number of copies allowed",
"type": "integer",
"format": "int64",
"example": 5
},
"minCount": {
"description": "The minimum number of copies allowed",
"type": "integer",
"format": "int64",
"example": 1
},
"threshold": {
"description": "The minimum required similarity (in %) of a found copy compared to the configured match region",
"type": "integer",
"format": "int64",
"example": 70
}
}
},
"findEdge": {
"type": "object",
"properties": {
"angleFound": {
"description": "The detected angle in degrees",
"type": "integer",
"format": "float64",
"example": 90
},
"angleRange": {
"description": "The configured angle allowance range",
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int32",
"example": 360
},
"low": {
"type": "integer",
"format": "int32",
"example": 0
}
}
},
"contrastPercent": {
"description": "The detected contrast percentage",
"type": "integer",
"format": "float64",
"example": 72.8
},
"contrastRange": {
"description": "The configured contrast allowance range",
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 100
},
"low": {
"type": "integer",
"format": "int64",
"example": 50
}
}
},
"enforceAngleRange": {
"description": "Whether the edge should be filtered by angle (°).",
"type": "boolean",
"example": true
},
"enforceStraightnessRange": {
"description": "Whether the edge should be filtered by straightness (%).",
"type": "boolean",
"example": true
},
"filterPolarity": {
"description": "The configured polarity for finding edges",
"type": "string",
"example": "ANY"
},
"sharpnessPercent": {
"description": "The detected sharpness percentage",
"type": "integer",
"format": "float64",
"example": 95
},
"sharpnessRange": {
"description": "The configured sharpness allowance range",
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 100
},
"low": {
"type": "integer",
"format": "int64",
"example": 80
}
}
},
"straightnessFound": {
"description": "The detected straightness percentage",
"type": "integer",
"format": "float64",
"example": 95
},
"straightnessRange": {
"description": "The configured straightness allowance range",
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int32",
"example": 100
},
"low": {
"type": "integer",
"format": "int32",
"example": 80
}
}
}
}
},
"findShapes": {
"type": "object",
"properties": {
"foundCount": {
"type": "integer",
"format": "int32",
"example": 1
},
"maxCount": {
"type": "integer",
"format": "int32",
"example": 5
},
"minCount": {
"type": "integer",
"format": "int32",
"example": 1
}
}
},
"fixture": {
"type": "object",
"properties": {
"coordinates": {
"type": "object",
"properties": {
"x": {
"type": "integer",
"format": "int32",
"example": 10
},
"y": {
"type": "integer",
"format": "int32",
"example": 10
}
}
},
"found": {
"type": "boolean",
"example": true
},
"rotationDegrees": {
"type": "integer",
"format": "int64",
"example": 90
}
}
},
"labelMatch": {
"type": "object",
"properties": {
"score": {
"type": "integer",
"format": "int64",
"example": 10
},
"threshold": {
"type": "integer",
"format": "int64",
"example": 10
}
}
},
"name": {
"type": "string",
"example": "Chicken Caesar Label"
},
"presenceAbsence": {
"type": "object",
"properties": {
"blueRange": {
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 150
},
"low": {
"type": "integer",
"format": "int64",
"example": 90
}
}
},
"checkForAbsence": {
"type": "boolean",
"example": true
},
"grayscaleRange": {
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 100
},
"low": {
"type": "integer",
"format": "int64",
"example": 20
}
}
},
"greenRange": {
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 150
},
"low": {
"type": "integer",
"format": "int64",
"example": 90
}
}
},
"hueRange": {
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 100
},
"low": {
"type": "integer",
"format": "int64",
"example": 20
}
}
},
"redRange": {
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 150
},
"low": {
"type": "integer",
"format": "int64",
"example": 90
}
}
},
"saturationRange": {
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 50
},
"low": {
"type": "integer",
"format": "int64",
"example": 10
}
}
},
"score": {
"type": "integer",
"format": "int64",
"example": 50
},
"threshold": {
"description": "DEPRECATED: Please use ThresholdRange instead.",
"type": "integer",
"format": "int64",
"example": 50
},
"thresholdMode": {
"description": "Indicates whether the pass sensitivity threshold was configured in \"Percentage\" or \"Pixel Count\" mode.",
"type": "string",
"example": "Percentage"
},
"thresholdRange": {
"description": "The configured pass sensitivity range. Based on the threshold mode, this value will be a percentage or a pixel count.",
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 80
},
"low": {
"type": "integer",
"format": "int64",
"example": 30
}
}
},
"valueRange": {
"type": "object",
"properties": {
"high": {
"type": "integer",
"format": "int64",
"example": 50
},
"low": {
"type": "integer",
"format": "int64",
"example": 10
}
}
}
}
},
"result": {
"type": "string",
"example": "PASS"
},
"textMatch": {
"type": "object",
"properties": {
"foundText": {
"type": "string",
"example": "ABCD"
},
"matchString": {
"type": "string",
"example": "ABCD"
}
}
}
}
}
},
"allRouteJobUpdates": {
"type": "object",
"properties": {
"job_updates": {
"type": "array",
"items": {
"$ref": "#/definitions/jobUpdateObject"
}
},
"sequence_id": {
"description": "Sequence ID of the last update returned in the response",
"type": "string",
"example": "eyJpZCI6MywiY3JlYXRlZF9hdCI6MTQ5OTQyOTIyMDAwMn0="
}
}
},
"jobStatus": {
"description": "The current state of the dispatch job.",
"type": "string",
"enum": [
"JobState_Unassigned",
"JobState_Scheduled",
"JobState_EnRoute",
"JobState_Arrived",
"JobState_Completed",
"JobState_Skipped"
],
"example": "JobState_Arrived"
},
"jobUpdateObject": {
"type": "object",
"properties": {
"changed_at_ms": {
"description": "Timestamp that this event was updated, represented as Unix milliseconds since epoch.",
"type": "integer",
"format": "int64",
"example": 1462881998034
},
"job_id": {
"description": "ID of the Samsara job.",
"type": "integer",
"format": "int64",
"example": 773
},
"job_state": {
"$ref": "#/definitions/jobStatus"
},
"prev_job_state": {
"$ref": "#/definitions/prevJobStatus"
},
"route": {
"$ref": "#/definitions/DispatchRouteWithoutETA"
},
"route_id": {
"description": "ID of the Samsara dispatch route.",
"type": "integer",
"format": "int64",
"example": 556
}
}
},
"prevJobStatus": {
"description": "The previous state of the dispatch job.",
"type": "string",
"enum": [
"JobState_Unassigned",
"JobState_Scheduled",
"JobState_EnRoute",
"JobState_Arrived",
"JobState_Completed",
"JobState_Skipped"
],
"example": "JobState_EnRoute"
}
},
"parameters": {
"addContactParam": {
"description": "Add a contact.",
"name": "contact",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/ContactInput"
}
},
"addressAddParam": {
"description": "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.",
"name": "addresses",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"addresses"
],
"properties": {
"addresses": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"formattedAddress",
"geofence"
],
"properties": {
"contactIds": {
"$ref": "#/definitions/ContactIds"
},
"formattedAddress": {
"description": "The full address associated with this address/geofence, as it might be recognized by maps.google.com",
"type": "string",
"example": "350 Rhode Island St, San Francisco, CA"
},
"geofence": {
"$ref": "#/definitions/AddressGeofence"
},
"name": {
"description": "The name of this address/geofence",
"type": "string",
"example": "Samsara HQ"
},
"notes": {
"$ref": "#/definitions/AddressNotes"
},
"tagIds": {
"$ref": "#/definitions/TagIds"
}
}
}
}
}
}
},
"addressUpdateParam": {
"description": "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.",
"name": "address",
"in": "body",
"required": true,
"schema": {
"type": "object",
"properties": {
"contactIds": {
"$ref": "#/definitions/ContactIds"
},
"formattedAddress": {
"description": "The full address associated with this address/geofence, as it might be recognized by maps.google.com",
"type": "string",
"example": "350 Rhode Island St, San Francisco, CA"
},
"geofence": {
"$ref": "#/definitions/AddressGeofence"
},
"name": {
"description": "The name of this address/geofence",
"type": "string",
"example": "Samsara HQ"
},
"notes": {
"$ref": "#/definitions/AddressNotes"
},
"tagIds": {
"$ref": "#/definitions/TagIds"
}
}
}
},
"applyToFutureRoutesParam": {
"name": "applyToFutureRoutes",
"in": "body",
"schema": {
"type": "object",
"properties": {
"apply_to_future_routes": {
"description": "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.",
"type": "boolean",
"example": true
}
}
}
},
"assetHistoryEndTimeParam": {
"type": "integer",
"format": "int64",
"description": "Timestamp in milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs.",
"name": "endMs",
"in": "query",
"required": true
},
"assetHistoryStartTimeParam": {
"type": "integer",
"format": "int64",
"description": "Timestamp in milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs.",
"name": "startMs",
"in": "query",
"required": true
},
"assetIdParam": {
"type": "integer",
"format": "int64",
"description": "ID of the asset. Must contain only digits 0-9.",
"name": "asset_id",
"in": "path",
"required": true
},
"createDriverParam": {
"description": "Driver creation body",
"name": "createDriverParam",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/DriverForCreate"
}
},
"createDvirParam": {
"description": "DVIR creation body",
"name": "createDvirParam",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"safe",
"inspectionType",
"userEmail"
],
"properties": {
"inspectionType": {
"description": "Only type 'mechanic' is currently accepted.",
"type": "string",
"enum": [
"mechanic"
],
"example": "mechanic"
},
"mechanicNotes": {
"description": "Any notes from the mechanic.",
"type": "string",
"example": "Replaced headlight on passenger side."
},
"odometerMiles": {
"description": "The current odometer of the vehicle.",
"type": "integer",
"example": 38426
},
"previousDefectsCorrected": {
"description": "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.",
"type": "boolean",
"example": true
},
"previousDefectsIgnored": {
"description": "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.",
"type": "boolean",
"example": false
},
"resolvedDefectIds": {
"description": "List of defect IDs to resolve. The defects must be associated with the provided vehicle or trailer.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"example": [
18,
19
]
},
"safe": {
"description": "Whether or not this vehicle or trailer is safe to drive.",
"type": "string",
"enum": [
"safe",
"unsafe"
],
"example": "safe"
},
"trailerId": {
"description": "Id of trailer being inspected. Either vehicleId or trailerId must be provided.",
"type": "integer",
"example": 11
},
"userEmail": {
"description": "The Samsara login email for the person creating the DVIR. The email must correspond to a Samsara user's email.",
"type": "string",
"example": "j.smith@yahoo.com"
},
"vehicleId": {
"description": "Id of vehicle being inspected. Either vehicleId or trailerId must be provided.",
"type": "integer",
"example": 10
}
}
}
},
"createMessagesParam": {
"description": "Text to send to a list of driverIds.",
"name": "createMessages",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"driverIds",
"text"
],
"properties": {
"driverIds": {
"description": "IDs of the drivers for whom the messages are sent to.",
"type": "array",
"items": {
"type": "number",
"format": "int64",
"example": 555
},
"example": [
111,
222,
333
]
},
"text": {
"description": "The text sent in the message.",
"type": "string",
"maxLength": 2500,
"example": "This is a message."
}
}
}
},
"createUserParam": {
"description": "User properties. Only one of organizationRoleId or tagRoles is required.",
"name": "user",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"name",
"email",
"authType"
],
"allOf": [
{
"$ref": "#/definitions/UpsertUserBase"
},
{
"type": "object",
"properties": {
"email": {
"description": "The email address of this user.",
"type": "string",
"example": "user@company.com"
}
}
}
]
}
},
"dataInputEndTimeParam": {
"type": "integer",
"format": "int64",
"description": "Timestamp in unix milliseconds representing the end of the period to fetch, inclusive. Used in combination with startMs. Defaults to nowMs.",
"name": "endMs",
"in": "query"
},
"dataInputIdParam": {
"type": "integer",
"format": "int64",
"description": "ID of the data input. Must contain only digits 0-9.",
"name": "data_input_id",
"in": "path",
"required": true
},
"dataInputStartTimeParam": {
"type": "integer",
"format": "int64",
"description": "Timestamp in unix milliseconds representing the start of the period to fetch, inclusive. Used in combination with endMs. defaults to nowMs.",
"name": "startMs",
"in": "query"
},
"documentCreateParam": {
"description": "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.",
"name": "createDocumentParams",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/DocumentCreate"
}
},
"documentQueryByParam": {
"enum": [
"created",
"updated"
],
"type": "string",
"format": "string",
"description": "Retrieve most recent documents based on either driverCreatedAtMs or serverUpdatedAtMs. If no value is provided, the default is driverCreatedAtMs.",
"name": "queryBy",
"in": "query"
},
"documentsDurationMsParam": {
"type": "integer",
"format": "int64",
"description": "Time in milliseconds that represents the duration before endMs to query. Defaults to 24 hours.",
"name": "durationMs",
"in": "query"
},
"documentsEndMsParam": {
"type": "integer",
"format": "int64",
"description": "Time in unix milliseconds that represents the oldest documents to return. Used in combination with durationMs. Defaults to now.",
"name": "endMs",
"in": "query"
},
"driverIdOrExternalIdParam": {
"type": "string",
"description": "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`",
"name": "driver_id_or_external_id",
"in": "path",
"required": true
},
"getMessagesDurationMsParam": {
"type": "integer",
"format": "int64",
"description": "Time in milliseconds that represents the duration before endMs to query. Defaults to 24 hours.",
"name": "durationMs",
"in": "query"
},
"getMessagesEndMsParam": {
"type": "integer",
"format": "int64",
"description": "Time in unix milliseconds that represents the end of time range of messages to return. Used in combination with durationMs. Defaults to now.",
"name": "endMs",
"in": "query"
},
"harshEventMsParam": {
"type": "integer",
"format": "int64",
"description": "Timestamp in milliseconds representing the timestamp of a harsh event.",
"name": "timestamp",
"in": "query",
"required": true
},
"jobUpdatesIncludeParam": {
"type": "string",
"description": "Optionally set include=route to include route object in response payload.",
"name": "include",
"in": "query"
},
"lastReceivedSequenceIDParam": {
"type": "string",
"description": "Sequence ID from the response payload of the last request. Defaults to fetching updates from last 24 hours.",
"name": "sequence_id",
"in": "query"
},
"paginationEndingBeforeParam": {
"type": "string",
"description": "Pagination parameter indicating the cursor position to return results before. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'startingAfter' parameter.",
"name": "endingBefore",
"in": "query"
},
"paginationLimitParam": {
"type": "number",
"format": "int64",
"description": "Pagination parameter indicating the number of results to return in this request. Used in conjunction with either 'startingAfter' or 'endingBefore'.",
"name": "limit",
"in": "query"
},
"paginationStartingAfterParam": {
"type": "string",
"description": "Pagination parameter indicating the cursor position to continue returning results after. Used in conjunction with the 'limit' parameter. Mutually exclusive with 'endingBefore' parameter.",
"name": "startingAfter",
"in": "query"
},
"reactivateDriverParam": {
"description": "Driver reactivation body",
"name": "reactivateDriverParam",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"reactivate"
],
"properties": {
"reactivate": {
"description": "True indicates that this driver should be reactivated.",
"type": "boolean"
}
}
}
},
"routeCreateParam": {
"name": "createDispatchRouteParams",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/DispatchRouteCreate"
}
},
"routeDurationParam": {
"type": "integer",
"format": "int64",
"description": "Time in milliseconds that represents the duration before end_time to query. Defaults to 24 hours.",
"name": "duration",
"in": "query"
},
"routeEndTimeParam": {
"type": "integer",
"format": "int64",
"description": "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.",
"name": "end_time",
"in": "query"
},
"routeHistoryEndTimeParam": {
"type": "integer",
"format": "int64",
"description": "Timestamp representing the end of the period to fetch, inclusive. Used in combination with start_time. Defaults to nowMs.",
"name": "end_time",
"in": "query"
},
"routeHistoryStartTimeParam": {
"type": "integer",
"format": "int64",
"description": "Timestamp representing the start of the period to fetch, inclusive. Used in combination with end_time. Defaults to 0.",
"name": "start_time",
"in": "query"
},
"routeIdOrExternalIdParam": {
"type": "string",
"description": "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`",
"name": "route_id_or_external_id",
"in": "path",
"required": true
},
"routeUpdateParam": {
"name": "updateDispatchRouteParams",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/DispatchRouteUpdate"
}
},
"safetyScoreEndMsParam": {
"type": "integer",
"format": "int64",
"description": "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.",
"name": "endMs",
"in": "query",
"required": true
},
"safetyScoreStartMsParam": {
"type": "integer",
"format": "int64",
"description": "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.",
"name": "startMs",
"in": "query",
"required": true
},
"sensorParam": {
"description": "List of sensor IDs to query.",
"name": "sensorParam",
"in": "body",
"required": true,
"schema": {
"type": "object",
"required": [
"sensors"
],
"properties": {
"sensors": {
"description": "List of sensor IDs to query.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"example": [
122
]
}
}
}
},
"tagCreateParam": {
"name": "tagCreateParams",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/TagCreate"
}
},
"tagIdsPathParam": {
"type": "array",
"items": {
"type": "string"
},
"description": "A comma-separated list of tag IDs. Example: `tagIds=1000,1001`",
"name": "tagIds",
"in": "query"
},
"tagModifyParam": {
"name": "tagModifyParams",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/TagModify"
}
},
"tagPathParam": {
"type": "integer",
"format": "int64",
"description": "ID of the tag. Must contain only digits 0-9.",
"name": "tag_id",
"in": "path",
"required": true
},
"tagUpdateParam": {
"name": "updateTagParams",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/TagUpdate"
}
},
"updateContactParam": {
"description": "Update the email, first name, last name, or phone number of a contact using the contact_id.",
"name": "contact",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/ContactInput"
}
},
"updateDriverParam": {
"description": "Driver update body",
"name": "updateDriverParam",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/DriverForUpdate"
}
},
"updateUserParam": {
"description": "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.",
"name": "user",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/UpsertUserBase"
}
},
"vehicleIdOrExternalIdParam": {
"type": "string",
"description": "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`.",
"name": "vehicle_id_or_external_id",
"in": "path",
"required": true
},
"visionCameraIdParam": {
"type": "integer",
"format": "int64",
"description": "The camera_id should be valid for the given accessToken.",
"name": "camera_id",
"in": "path",
"required": true
},
"visionDurationMsParam": {
"type": "integer",
"format": "int64",
"description": "DurationMs is a required param. This works with the EndMs parameter. Indicates the duration in which the visionRuns will be fetched",
"name": "durationMs",
"in": "query",
"required": true
},
"visionEndMsParam": {
"type": "integer",
"format": "int64",
"description": "EndMs is an optional param. It will default to the current time.",
"name": "endMs",
"in": "query"
},
"visionIncludeParam": {
"type": "string",
"description": "Include is a filter parameter. Accepts 'pass', 'reject' or 'no_read'.",
"name": "include",
"in": "query"
},
"visionLimitParam": {
"type": "integer",
"format": "int64",
"description": "Limit is an integer value from 1 to 1,000.",
"name": "limit",
"in": "query"
},
"visionProgramIdParam": {
"type": "integer",
"format": "int64",
"description": "The configured program's ID on the camera.",
"name": "program_id",
"in": "query"
},
"visionProgramIdPathParam": {
"type": "integer",
"format": "int64",
"description": "The configured program's ID on the camera.",
"name": "program_id",
"in": "path",
"required": true
},
"visionStartAtMsParam": {
"type": "integer",
"format": "int64",
"description": "EndMs is an optional param. It will default to the current time.",
"name": "startedAtMs",
"in": "query"
},
"visionStartAtMsPathParam": {
"type": "integer",
"format": "int64",
"description": "Started_at_ms is a required param. Indicates the start time of the run to be fetched.",
"name": "started_at_ms",
"in": "path",
"required": true
}
},
"securityDefinitions": {
"AccessTokenHeader": {
"type": "apiKey",
"name": "Authorization: Bearer",
"in": "header"
},
"AccessTokenParameter": {
"type": "apiKey",
"name": "access_token",
"in": "query"
},
"OAuth2": {
"type": "oauth2",
"flow": "accessCode",
"authorizationUrl": "https://api.samsara.com/oauth2/authorize",
"tokenUrl": "https://api.samsara.com/oauth2/token"
}
},
"tags": [
{
"description": "Access to fleet data",
"name": "Fleet"
},
{
"description": "Access to industrial data",
"name": "Industrial"
},
{
"description": "Access to sensor data",
"name": "Sensors"
},
{
"description": "Access to asset specific data",
"name": "Assets"
},
{
"description": "Access to safety specific data",
"name": "Safety"
},
{
"description": "Access to user data",
"name": "Users"
},
{
"description": "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.",
"name": "Contacts"
}
]
}