diff --git a/swagger.json b/swagger.json index e250e4b..365efa8 100644 --- a/swagger.json +++ b/swagger.json @@ -2,7 +2,7 @@ "swagger": "2.0", "info": { "title": "Samsara API", - "version": "1.0.0", + "version": "pre-release preview", "description": "# Introduction\n\nSamsara provides API endpoints for interacting with Samsara Cloud, 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 Cloud API is a [RESTful API](https://en.wikipedia.org/wiki/Representational_state_transfer) accessed by an [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) client such as wget or curl, or HTTP libraries of most modern programming languages including python, ruby, java. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We allow you to interact securely with our API from a client-side web application (though you should never expose your secret API key). [JSON](http://www.json.org/) is returned by all API responses, including errors. If you’re familiar with what you can build with a REST API, the following API reference guide will be your go-to resource.\n\nAPI access to the Samsara cloud is available to all Samsara administrators. To start developing with Samsara APIs you will need to [obtain your API keys](#section/Authentication) to authenticate your API requests.\n\nIf you have any questions you can reach out to us on [support@samsara.com](mailto:support@samsara.com)\n\n# Endpoints\n\nAll our APIs can be accessed through HTTP requests to URLs like:\n\n```curl\nhttps://api.samsara.com//\n```\n\nAll our APIs are [versioned](#section/Versioning). If we intend to make breaking changes to an API which either changes the response format or request parameter, we will increment the version.\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->Organization->API 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 [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Provide your API token as the basic access_token value in the URL. You do not need to provide a password.\n\n```curl\nhttps://api.samsara.com//?access_token={{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# Request Methods\n\nOur API endpoints use [HTTP request methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) to specify the desired operation to be performed. The documentation below specified request method supported by each endpoint and the resulting action.\n\n## GET\n\nGET requests are typically used for fetching data (like data for a particular driver).\n\n## POST\n\nPOST requests are typically used for creating or updating a record (like adding new tags to the system). With that being said, a few of our POST requests can be used for fetching data (like current location data of your fleet).\n\n## PUT\n\nPUT requests are typically used for updating an existing record (like updating all devices associated with a particular tag).\n\n## PATCH\n\nPATCH requests are typically used for modifying an existing record (like modifying a few devices associated with a particular tag).\n\n## DELETE\n\nDELETE requests are used for deleting a record (like deleting a tag from the system).\n\n# Response Codes\n\nAll API requests will respond with appropriate [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). Your API client should handle each response class differently.\n\n## 2XX\n\nThese are successful responses and indicate that the API request returned the expected response.\n\n## 4XX\n\nThese indicate that there was a problem with the request like a missing parameter or invalid values. Check the response for specific [error details](#section/Error-Responses). Requests that respond with a 4XX status code, should be modified before retrying.\n\n## 5XX\n\nThese indicate server errors when the server is unreachable or is misconfigured. In this case, you should retry the API request after some delay.\n\n# Error Responses\n\nIn case of a 4XX status code, the body of the response will contain information to briefly explain the error reported. To help debugging the error, you can refer to the following table for understanding the error message.\n\n| Status Code | Message | Description |\n|-------------|----------------|-------------------------------------------------------------------|\n| 401 | Invalid token | The API token is invalid and could not be authenticated. Please refer to the [authentication section](#section/Authentication). |\n| 404 | Page not found | The API endpoint being accessed is invalid. |\n| 400 | Bad request | Default response for an invalid request. Please check the request to make sure it follows the format specified in the documentation. |\n\n# Versioning\n\nAll our APIs are versioned. Our current API version is `v1` and we are continuously working on improving it further and provide additional endpoints. If we intend to make breaking changes to an API which either changes the response format or request parameter, we will increment the version. Thus, you can use our current API version worry free.\n\n# FAQs\n\nCheck out our [responses to FAQs here](https://kb.samsara.com/hc/en-us/sections/360000538054-APIs). Don’t see an answer to your question? Reach out to us on [support@samsara.com](mailto:support@samsara.com)." }, "host": "api.samsara.com", @@ -40,9 +40,202 @@ { "name": "Default", "description": "All Samsara API endpoints" + }, + { + "name": "Users", + "description": "Access to user data" } ], "paths": { + "/users": { + "get": { + "tags": [ + "Default", "Users" + ], + "summary": "/users", + "description": "Get all users in the organization.", + "operationId": "list_users", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" } + ], + "responses": { + "200": { + "description": "List of users.", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/User" + } + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "post": { + "tags": [ + "Default", "Users" + ], + "summary": "/users", + "description": "Add a user to the organization.", + "operationId": "create_user", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { "$ref": "#/parameters/createUserParam" } + ], + "responses": { + "200": { + "description": "User successfully created.", + "schema": { + "$ref": "#/definitions/User" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/users/{user_id}": { + "get": { + "tags": [ + "Default", "Users" + ], + "summary": "/users/{user_id:[0-9]+}", + "description": "Get a user.", + "operationId": "get_user", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { + "name": "user_id", + "in": "path", + "required": true, + "description": "ID of the user.", + "type": "integer", + "format": "int64" + } + ], + "responses": { + "200": { + "description": "User record.", + "schema": { + "$ref": "#/definitions/User" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "delete": { + "tags": [ + "Default", "Users" + ], + "summary": "/users/{user_id:[0-9]+}", + "description": "Remove a user from the organization.", + "operationId": "delete_user", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { + "name": "user_id", + "in": "path", + "required": true, + "description": "ID of the user.", + "type": "integer", + "format": "int64" + } + ], + "responses": { + "200": { + "description": "The user was successfully removed." + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "patch": { + "tags": [ + "Default", "Users" + ], + "summary": "/users/{user_id:[0-9]+}", + "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.", + "operationId": "update_user", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { "$ref": "#/parameters/updateUserParam" }, + { + "name": "user_id", + "in": "path", + "required": true, + "description": "ID of the user.", + "type": "integer", + "format": "int64" + } + ], + "responses": { + "200": { + "description": "User successfully updated.", + "schema": { + "$ref": "#/definitions/User" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "put": { + "tags": [ + "Default", "Users" + ], + "summary": "/users/{user_id:[0-9]+}", + "description": "Replace all fields on a user with the supplied fields. Any fields not supplied will be set to null.", + "operationId": "replace_user", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { "$ref": "#/parameters/createUserParam" }, + { + "name": "user_id", + "in": "path", + "required": true, + "description": "ID of the user.", + "type": "integer", + "format": "int64" + } + ], + "responses": { + "200": { + "description": "User successfully created.", + "schema": { + "$ref": "#/definitions/User" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, "/sensors/list": { "post": { "tags": [ @@ -568,25 +761,24 @@ } } }, - "/fleet/drivers/{driver_id}": { - "parameters": [ + "/fleet/drivers/{driver_id | external_id}": { + "get": { + "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "driver_id", + "name": "driver_id | external_id", "in": "path", "required": true, - "description": "ID of the driver.", - "type": "integer", - "format": "int64" + "description": "Either the ID of the driver (integer) or corresponding external ID (alphanumeric string). One of these two parameters must be specified to identify the driver.", + "type": "string" } ], - "get": { "tags": [ "Default", "Fleet", "Drivers" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}", "description": "Fetch driver by id.", "operationId": "getDriverById", "consumes": [ @@ -610,11 +802,64 @@ } } }, + "patch": { + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "driver_id | external_id", + "in": "path", + "required": true, + "description": "Either the ID of the driver (integer) or corresponding external ID (alphanumeric string). One of these two parameters must be specified to identify the driver.", + "type": "string" + }, + { "$ref": "#/parameters/driverParam" } + ], + "tags": [ + "Default", "Fleet", "Drivers" + ], + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}", + "description": "Update driver by id.", + "operationId": "patchDriverById", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "Returns the driver for the given driver_id or external_id.", + "schema": { + "$ref": "#/definitions/CurrentDriver" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, "delete": { + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "driver_id | external_id", + "in": "path", + "required": true, + "description": "Either the ID of the driver (integer) or corresponding external ID (alphanumeric string). One of these two parameters must be specified to identify the driver.", + "type": "string" + } + ], "tags": [ "Default", "Fleet", "Drivers" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}", "description": "Deactivate a driver with the given driver_id.", "operationId": "deactivateDriver", "consumes": [ @@ -625,7 +870,7 @@ ], "responses": { "200": { - "description": "Successfully deactivated the driver, which is now referenced by /fleet/drivers/inactive/{driver_id}." + "description": "Successfully deactivated the driver, which is now referenced by /fleet/drivers/inactive/{driver_id | external_id}." }, "default": { "description": "Unexpected error.", @@ -673,25 +918,24 @@ } } }, - "/fleet/drivers/inactive/{driver_id}": { + "/fleet/drivers/inactive/{driver_id | external_id}": { "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "driver_id", + "name": "driver_id | external_id", "in": "path", "required": true, - "description": "ID of the deactivated driver.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the deactivated driver or corresponding external ID (alphanumeric string).", + "type": "string" } ], "get": { "tags": [ "Default", "Fleet", "Drivers" ], - "summary": "/fleet/drivers/inactive/{driver_id:[0-9]+}", + "summary": "/fleet/drivers/inactive/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}", "description": "Fetch deactivated driver by driver_id.", "operationId": "getDeactivatedDriverById", "consumes": [ @@ -719,7 +963,7 @@ "tags": [ "Default", "Fleet", "Drivers" ], - "summary": "/fleet/drivers/inactive/{driver_id:[0-9]+}", + "summary": "/fleet/drivers/inactive/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}", "description": "Reactivate the inactive driver having driver_id.", "operationId": "reactivateDriverById", "consumes": [ @@ -817,12 +1061,12 @@ } } }, - "/fleet/drivers/{driver_id}/hos_daily_logs": { + "/fleet/drivers/{driver_id | external_id}/hos_daily_logs": { "post": { "tags": [ "Fleet", "Default" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}/hos_daily_logs", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/hos_daily_logs", "description": "Get summarized daily HOS charts for a specified driver.", "operationId": "get_fleet_drivers_hos_daily_logs", "parameters": [ @@ -830,12 +1074,11 @@ "$ref": "#/parameters/accessTokenParam" }, { - "name": "driver_id", + "name": "driver_id | external_id", "in": "path", "required": true, - "description": "ID of the driver with HOS logs.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the driver with HOS logs or corresponding external ID (alphanumeric string).", + "type": "string" }, { "name": "hosLogsParam", @@ -959,44 +1202,57 @@ } } }, - "/fleet/hos_logs_summary": { - "post": { + "/fleet/vehicles/{vehicle_id}/unassigned_driving_segments": { + "get": { "tags": [ "Fleet", "Default" ], - "summary": "/fleet/hos_logs_summary", - "description": "Get the current HOS status for all drivers in the group.", - "operationId": "get_fleet_hos_logs_summary", + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/unassigned_driving_segments", + "description": "Get the unassigned driving segments for a specified range.", + "operationId": "getUnassignedDrivingSegmentsByVehicleId", "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "hosLogsParam", + "name": "vehicle_id", + "in": "path", "required": true, - "in": "body", + "description": "ID of the vehicle with the associated unassigned driving segments.", + "type": "integer", + "format": "int64" + }, + { + "name": "start_ms", + "in": "query", + "required": true, + "description": "Beginning of the time range, specified in milliseconds UNIX time.", + "type": "integer", + "format": "int64" + }, + { + "name": "end_ms", + "in": "query", + "required": true, + "description": "End of the time range, specified in milliseconds UNIX time.", + "type": "integer", + "format": "int64" + }, + ], + "responses": { + "200": { + "description": "Unassigned driving segments for provided duration and vehicle.", "schema": { "type": "object", - "required": [ - "groupId" - ], "properties": { - "groupId": { - "type": "integer", - "format": "int64", - "description": "Group ID to query.", - "example": 101 + "unassigned_driving_segments": { + "type": "array", + "items": { + "$ref": "#/definitions/UnassignedDrivingSegment" + } } } } - } - ], - "responses": { - "200": { - "description": "HOS logs for the specified driver.", - "schema": { - "$ref": "#/definitions/HosLogsSummaryResponse" - } }, "default": { "description": "Unexpected error.", @@ -1007,30 +1263,187 @@ } } }, - "/fleet/maintenance/dvirs": { + "/fleet/vehicles/{vehicle_id}/unassigned_driving_segments/{segment_id}": { "get": { "tags": [ - "Fleet","Default" + "Fleet", "Default" ], - "summary": "/fleet/maintenance/dvirs", - "description": "Get the DVIR for the org with the time constraints", - "operationId": "get_dvirs", + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/unassigned_driving_segments/{segment_id}", + "description": "Fetch an unassigned driving segment by vehicle ID and segment ID.", + "operationId": "getUnassignedDrivingSegmentByVehicleIdAndSegmentId", "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "end_ms", - "description": "time in millis until the last dvir log.", + "name": "vehicle_id", + "in": "path", "required": true, - "in": "query", - "type": "integer" + "description": "ID of the vehicle with the associated unassigned driving segments.", + "type": "integer", + "format": "int64" }, { - "name": "duration_ms", - "description": "time in millis which corresponds to the duration before the end_ms.", + "name": "segment_id", + "in": "path", "required": true, - "in": "query", + "description": "ID of the unassigned driving segment.", + "type": "string", + "format": "string" + }, + ], + "responses": { + "200": { + "description": "Unassigned driving segment log for the specified vehicle ID and segment ID.", + "schema": { + "$ref": "#/definitions/UnassignedDrivingSegment" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "patch": { + "tags": [ + "Fleet", "Default" + ], + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/unassigned_driving_segments/{segment_id}", + "description": "Update an unassigned driving segment.", + "operationId": "patchUnassignedDrivingSegment", + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "vehicle_id", + "in": "path", + "required": true, + "description": "ID of the vehicle with the associated unassigned driving segments.", + "type": "integer", + "format": "int64" + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "ID of the unassigned driving segment.", + "type": "string", + "format": "string" + }, + { + "name": "unassignedDrivingSegmentParams", + "required": true, + "in": "body", + "schema": { + "type": "object", + "properties": { + "annotation": { + "type": "string", + "description": "Annotation to give this segment.", + "example": "Drive time" + }, + "driverId": { + "type": "integer", + "format": "int64", + "description": "Driver ID to assign to this segment.", + "example": 719 + } + } + } + } + ], + "responses": { + "200": { + "description": "The unassigned driving segment that was updated.", + "schema": { + "$ref": "#/definitions/UnassignedDrivingSegment" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/fleet/hos_logs_summary": { + "post": { + "tags": [ + "Fleet", "Default" + ], + "summary": "/fleet/hos_logs_summary", + "description": "Get the current HOS status for all drivers in the group.", + "operationId": "get_fleet_hos_logs_summary", + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "hosLogsParam", + "required": true, + "in": "body", + "schema": { + "type": "object", + "required": [ + "groupId" + ], + "properties": { + "groupId": { + "type": "integer", + "format": "int64", + "description": "Group ID to query.", + "example": 101 + } + } + } + } + ], + "responses": { + "200": { + "description": "HOS logs for the specified driver.", + "schema": { + "$ref": "#/definitions/HosLogsSummaryResponse" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/fleet/maintenance/dvirs": { + "get": { + "tags": [ + "Fleet","Default" + ], + "summary": "/fleet/maintenance/dvirs", + "description": "Get DVIRs for the org within provided time constraints", + "operationId": "get_dvirs", + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "end_ms", + "description": "time in millis until the last dvir log.", + "required": true, + "in": "query", + "type": "integer" + }, + { + "name": "duration_ms", + "description": "time in millis which corresponds to the duration before the end_ms.", + "required": true, + "in": "query", "type": "integer" }, { @@ -1043,7 +1456,7 @@ ], "responses": { "200": { - "description": "DVIR's for the specified group and duration.", + "description": "DVIRs for the specified duration.", "schema": { "$ref": "#/definitions/DvirListResponse" } @@ -1055,6 +1468,32 @@ } } } + }, + "post": { + "tags": [ + "Fleet","Default" + ], + "summary": "/fleet/maintenance/dvirs", + "description": "Create a new dvir, marking a vehicle or trailer safe or unsafe.", + "operationId": "create_dvir", + "parameters": [ + { "$ref": "#/parameters/accessTokenParam" }, + { "$ref": "#/parameters/createDvirParam" } + ], + "responses": { + "200": { + "description": "Newly created DVIR.", + "schema": { + "$ref": "#/definitions/DvirBase" + } + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } } }, "/fleet/hos_authentication_logs": { @@ -1535,18 +1974,17 @@ } } }, - "/fleet/drivers/{driver_id}/dispatch/routes": { + "/fleet/drivers/{driver_id | external_id}/dispatch/routes": { "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "driver_id", + "name": "driver_id | external_id", "in": "path", "required": true, - "description": "ID of the driver with the associated routes.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the driver with the associated routes or corresponding external ID (alphanumeric string).", + "type": "string" } ], "get": { @@ -1555,7 +1993,7 @@ "Fleet", "Routes" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}/dispatch/routes", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", "description": "Fetch all of the dispatch routes for a given driver.", "operationId": "getDispatchRoutesByDriverId", "consumes": [ @@ -1587,7 +2025,7 @@ "tags": [ "Default", "Fleet", "Routes" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}/dispatch/routes", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", "description": "Create a new dispatch route for the driver with driver_id.", "operationId": "createDriverDispatchRoute", "consumes": [ @@ -1615,6 +2053,46 @@ } } }, + "/fleet/vehicles/{vehicle_id | external_id}": { + "parameters": [ + { + "$ref": "#/parameters/accessTokenParam" + }, + { + "name": "vehicle_id | external_id", + "in": "path", + "required": true, + "description": "ID (integer) of the vehicle or corresponding external ID (alphanumeric string).", + "type": "string" + } + ], + "patch": { + "tags": [ + "Default", + "Fleet" + ], + "summary": "/fleet/vehicles/{vehicle_id | external_id}", + "description": "Updates a vehicle given either a vehicle ID or external ID (alphanumeric string)", + "operationId": "updateVehicle", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "Returns updated vehicle." + }, + "default": { + "description": "Unexpected error.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, "/fleet/vehicles/locations": { "parameters": [ { @@ -1665,18 +2143,17 @@ } } }, - "/fleet/vehicles/{vehicle_id}/dispatch/routes": { + "/fleet/vehicles/{vehicle_id | external_id}/dispatch/routes": { "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "vehicle_id", + "name": "vehicle_id | external_id", "in": "path", "required": true, - "description": "ID of the vehicle with the associated routes.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the vehicle with the associated routes or corresponding external ID (alphanumeric string).", + "type": "string" } ], "get": { @@ -1685,7 +2162,7 @@ "Fleet", "Routes" ], - "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/dispatch/routes", + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", "description": "Fetch all of the dispatch routes for a given vehicle.", "operationId": "getDispatchRoutesByVehicleId", "consumes": [ @@ -1700,7 +2177,7 @@ ], "responses": { "200": { - "description": "Returns all of the dispatch routes for the given vehicle_id.", + "description": "Returns all of the dispatch routes for the given vehicle_id or external_id.", "schema": { "$ref": "#/definitions/DispatchRoutes" } @@ -1717,8 +2194,8 @@ "tags": [ "Default", "Fleet", "Routes" ], - "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/dispatch/routes", - "description": "Create a new dispatch route for the vehicle with vehicle_id.", + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/dispatch/routes", + "description": "Create a new dispatch route for the vehicle with vehicle_id or external_id.", "operationId": "createVehicleDispatchRoute", "consumes": [ "application/json" @@ -1745,18 +2222,17 @@ } } }, - "/fleet/vehicles/{vehicle_id}/locations": { + "/fleet/vehicles/{vehicle_id | external_id}/locations": { "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "vehicle_id", + "name": "vehicle_id | external_id", "in": "path", "required": true, - "description": "ID of the vehicle with the associated routes.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the vehicle with the associated routes or corresponding external ID (alphanumeric string).", + "type": "string" }, { "name": "startMs", @@ -1780,7 +2256,7 @@ "Default", "Fleet" ], - "summary": "/fleet/vehicles/{vehicle_id:[0-9]+}/locations", + "summary": "/fleet/vehicles/{vehicle_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/locations", "description": "Fetch locations for a given vehicle between a start/end time. The maximum query duration is one hour.", "operationId": "getVehicleLocations", "consumes": [ @@ -1876,18 +2352,17 @@ } } }, - "/fleet/drivers/{driver_id}/documents": { + "/fleet/drivers/{driver_id | external_id}/documents": { "parameters": [ { "$ref": "#/parameters/accessTokenParam" }, { - "name": "driver_id", + "name": "driver_id | external_id", "in": "path", "required": true, - "description": "ID of the driver for whom the document is created.", - "type": "integer", - "format": "int64" + "description": "ID (integer) of the driver for whom the document is created or corresponding external ID (alphanumeric string).", + "type": "string" } ], "post": { @@ -1895,7 +2370,7 @@ "Default", "Fleet" ], - "summary": "/fleet/drivers/{driver_id:[0-9]+}/documents", + "summary": "/fleet/drivers/{driver_id:[0-9]+ | external_id:[a-zA-Z0-9]+}/documents", "description": "Create a driver document for the given driver.", "operationId": "createDriverDocument", "consumes": [ @@ -2974,6 +3449,14 @@ "format": "int64", "example": 112 }, + "externalIds": { + "type": "object", + "description": "Map of all external ids for vehicle", + "additionalProperties": { + "type": "string" + }, + "example": {"maintenanceId": "123", "internalVehicleId": "BNUN2798"} + }, "name": { "type": "string", "description": "Name of the vehicle.", @@ -3021,6 +3504,14 @@ "format": "int64", "example": 112 }, + "externalIds" : { + "type": "object", + "description": "Dictionary of external IDs (string key-value pairs)", + "additionalProperties": { + "type": "string" + }, + "example": {"maintenanceId": "123", "internalVehicleId": "BNUN2798"} + }, "name": { "type": "string", "description": "Name of the vehicle.", @@ -3085,6 +3576,14 @@ "format": "int64", "example": 112 }, + "externalIds": { + "type": "object", + "description": "Map of all external ids for vehicle", + "additionalProperties": { + "type": "string" + }, + "example": {"maintenanceId": "123", "internalVehicleId": "BNUN2798"} + }, "j1939": { "type": "object", "description": "J1939 based data. Null if no data is available.", @@ -3171,6 +3670,50 @@ } } }, + "UnassignedDrivingSegment": { + "type": "object", + "description": "A driving segment that has no associated driver.", + "properties": { + "id": { + "type": "string", + "format": "string", + "example": "MTU0MjE1NzkzNDAwMA", + }, + "vehicle_id": { + "type": "integer", + "format": "int64", + "example": 212014918086169, + }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" + }, + "start_ms": { + "type": "integer", + "format": "int64", + "example": 1523059200000, + }, + "end_ms": { + "type": "integer", + "format": "int64", + "example": 1523059200000, + }, + "annotation": { + "type": "string", + "description": "Annotation for the driving segment.", + "example": "Drive time" + }, + "pending_driver_id": { + "type": "integer", + "format": "int64", + "example": 719, + }, + "created_at_ms": { + "type": "integer", + "format": "int64", + "example": 1523059200000, + }, + } + }, "TemperatureResponse": { "type": "object", "description": "Contains the current temperatures of a sensor.", @@ -3316,30 +3859,99 @@ } } }, - "TripResponse": { + "VehicleIdResponse": { + "type": "integer", + "description": "ID of the vehicle.", + "example": 444 + }, + "DriverIdResponse": { + "type": "integer", + "description": "ID of the driver.", + "example": 719 + }, + "ExternalDriverResponse" : { "type": "object", - "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.", + "description": "Driver object", "properties": { - "trips": { - "type": "array", - "items": { - "type": "object", - "properties": { - "startMs": { - "type": "integer", - "description": "Beginning of the trip in UNIX milliseconds.", - "example": 1462878398034 - }, - "startCoordinates": { - "type": "object", - "description": "Start (latitude, longitude) in decimal degrees.", - "properties": { - "latitude": { - "type": "number", - "format": "float", - "example": 29.443702345 - }, - "longitude": { + "id": { + "type": "integer", + "description": "ID of the driver.", + "example": 719 + }, + "externalIds" : { + "type": "object", + "description": "Dictionary of external IDs (string key-value pairs)", + "additionalProperties": { + "type": "string" + }, + "example": {"payrollId": "123", "internalDriverId": "250020"} + } + } + }, + "ExternalVehicleResponse": { + "type": "object", + "description": "Vehicle object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "ID of the vehicle.", + "example": 444 + }, + "externalIds" : { + "type": "object", + "description": "Dictionary of external IDs (string key-value pairs)", + "additionalProperties": { + "type": "string" + }, + "example": {"internalVehicleId": "CITY320025"} + } + } + }, + "ExternalCurrentVehicleResponse": { + "type": "object", + "description": "Vehicle object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "ID of the vehicle used for the dispatch job.", + "example": 879 + }, + "externalIds" : { + "type": "object", + "description": "Dictionary of external IDs (string key-value pairs)", + "additionalProperties": { + "type": "string" + }, + "example": {"internalVehicleId": "ABFS18600"} + } + } + }, + "TripResponse": { + "type": "object", + "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.", + "properties": { + "trips": { + "type": "array", + "items": { + "type": "object", + "properties": { + "startMs": { + "type": "integer", + "description": "Beginning of the trip in UNIX milliseconds.", + "example": 1462878398034 + }, + "startCoordinates": { + "type": "object", + "description": "Start (latitude, longitude) in decimal degrees.", + "properties": { + "latitude": { + "type": "number", + "format": "float", + "example": 29.443702345 + }, + "longitude": { "type": "number", "format": "float", "example": -98.502888123 @@ -3403,9 +4015,10 @@ "example": 32000 }, "driverId": { - "type": "integer", - "description": "ID of the driver.", - "example": 719 + "$ref": "#/definitions/DriverIdResponse" + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "startOdometer": { "type": "integer", @@ -3489,11 +4102,23 @@ "description": "ID of the vehicle assigned to the driver for static vehicle assignments. (uncommon).", "example": 444 }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" + }, "groupId": { "type": "integer", "format": "int64", "description": "ID of the group if the organization has multiple groups (uncommon).", "example": 101 + }, + "driverId": { + "type": "integer", + "format": "int64", + "description": "ID of the driver", + "example": 719 + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" } } }, @@ -3542,7 +4167,10 @@ "format": "int64", "description": "ID of the vehicle that this driver is currently assigned to. Omitted if there is no current vehicle assignment for this driver.", "example": 879 - } + }, + "currentVehicle": { + "$ref": "#/definitions/ExternalCurrentVehicleResponse" + }, } }, { @@ -3586,6 +4214,14 @@ "type": "string", "description": "Name of the driver.", "example": "Fred Jacobs" + }, + "externalIds" : { + "type": "object", + "description": "Dictionary of external IDs (string key-value pairs)", + "additionalProperties": { + "type": "string" + }, + "example": {"payrollId": "123", "internalDriverId": "250020"} } } } @@ -3604,7 +4240,10 @@ "type": "integer", "format": "int64", "description": "ID of the driver.", - "example": 444 + "example": 719 + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "driverName": { "type": "string", @@ -3671,6 +4310,30 @@ "description": "Milliseconds spent on duty or driving.", "example": 691200 }, + "onDutyMs": { + "type": "number", + "format": "int64", + "description": "Duration in milliseconds that driver was on duty during the requested time range.", + "example": 21600000 + }, + "driveMs": { + "type": "number", + "format": "int64", + "description": "Duration in milliseconds that driver was driving during the requested time range.", + "example": 21600000 + }, + "pendingOnDutyMs": { + "type": "number", + "format": "int64", + "description": "Duration in milliseconds that driver was on duty during the requested time range for pending logs.", + "example": 21600000 + }, + "pendingDriveMs": { + "type": "number", + "format": "int64", + "description": "Duration in milliseconds that driver was driving during the requested time range for pending logs.", + "example": 21600000 + }, "certified": { "type": "boolean", "description": "Whether this HOS day chart was certified by the driver." @@ -3725,7 +4388,10 @@ "type": "integer", "format": "int64", "description": "ID of the driver.", - "example": 444 + "example": 719 + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "driverName": { "type": "string", @@ -3801,213 +4467,7 @@ "dvirs": { "type": "array", "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64", - "description": "The id of this DVIR record.", - "example": 19 - }, - "timeMs": { - "type": "integer", - "format": "int64", - "description": "Timestamp of this DVIR in UNIX milliseconds.", - "example": 1453449599999 - }, - "inspectionType": { - "type": "string", - "description": "Inspection type of the DVIR.", - "example": "pre trip" - }, - "vehicle": { - "type": "object", - "description": "The vehicle on which DVIR was done.", - "properties": { - "id": { - "type": "integer", - "format": "int64", - "description": "The vehicle id on which DVIR was done.", - "example": 19 - }, - "name": { - "type": "string", - "description": "The vehicle on which DVIR was done.", - "example": "Storer's vehicle 19" - } - } - }, - "vehicleDefects": { - "type": "array", - "description": "Defects registered for the vehicle which was part of the DVIR.", - "items" : { - "type" : "object", - "properties" : { - "defectType": { - "type": "string", - "description": "The type of DVIR defect", - "example": "Air Compressor" - }, - "comment": { - "type": "string", - "description": "The comment describing the type of DVIR defect", - "example": "Air Compressor not working" - } - } - } - }, - "odometerMiles": { - "type": "integer", - "format": "int64", - "description": "The odometer reading in miles for the vehicle when the DVIR was done.", - "example": 49912 - }, - "trailerName": { - "type": "string", - "description": "The name of the trailer which was part of the DVIR.", - "example": "Storer's Trailer 19" - }, - "trailerId": { - "type": "integer", - "description": "The id of the trailer which was part of the DVIR.", - "example": 19 - }, - "trailerDefects": { - "type": "array", - "description": "Defects registered for the trailer which was part of the DVIR.", - "items" : { - "type" : "object", - "properties" : { - "defectType": { - "type": "string", - "description": "The type of DVIR defect", - "example": "Air Compressor" - }, - "comment": { - "type": "string", - "description": "The comment describing the type of DVIR defect", - "example": "Air Compressor not working" - } - } - } - }, - "mechanicNotes": { - "type": "string", - "description": "The mechanics notes on the DVIR.", - "example": "The vehicle is now safe." - }, - "vehicleCondition": { - "type": "string", - "description": "The condition of vechile on which DVIR was done.", - "example": "SATISFACTORY" - }, - "defectsCorrected": { - "type": "boolean", - "description": "Signifies if the defects on the vehicle corrected after the DVIR is done.", - "example": true - }, - "defectsNeedNotBeCorrected": { - "type": "boolean", - "description": "Signifies if the defects on this vehicle can be ignored.", - "example": false - }, - "authorSignature": { - "type": "object", - "description": "The authors signature for the DVIR.", - "properties": { - "type": { - "type": "string", - "description": "Type corresponds to whether the signature corresponds to driver|mechanic.", - "example": "driver" - }, - "name": { - "type": "string", - "description": "The name of the driver or mechanic who signed the DVIR.", - "example": "driver" - }, - "username": { - "type": "string", - "description": "Username of the driver|mechanic who signed the DVIR.", - "example": "driver" - }, - "email": { - "type": "string", - "description": "Email of the driver|mechanic who signed the DVIR.", - "example": "driver" - }, - "signedAt": { - "type": "integer", - "format": "int64", - "description": "The time in millis when the DVIR was signed", - "example": 12535500000 - } - } - }, - "mechanicOrAgentSignature": { - "type": "object", - "description": "The mechanic's or agent's signature for the DVIR.", - "properties": { - "type": { - "type": "string", - "description": "Type corresponds to whether the signature corresponds to driver|mechanic.", - "example": "driver" - }, - "name": { - "type": "string", - "description": "The name of the agent or mechanic who signed the DVIR.", - "example": "driver" - }, - "username": { - "type": "string", - "description": "Username of the agent|mechanic who signed the DVIR.", - "example": "driver" - }, - "email": { - "type": "string", - "description": "Email of the agent|mechanic who signed the DVIR.", - "example": "driver" - }, - "signedAt": { - "type": "integer", - "format": "int64", - "description": "The time in millis when the DVIR was signed", - "example": 12535500000 - } - } - }, - "nextDriverSignature": { - "type": "object", - "description": "The next driver signature for the DVIR.", - "properties": { - "type": { - "type": "string", - "description": "Type corresponds to driver.", - "example": "driver" - }, - "name": { - "type": "string", - "description": "The name of the driver who signed the next DVIR on this vehicle.", - "example": "driver" - }, - "username": { - "type": "string", - "description": "Username of the driver who signed the next DVIR on this vehicle.", - "example": "driver" - }, - "email": { - "type": "string", - "description": "Email of the driver who signed the next DVIR on this vehicle.", - "example": "driver" - }, - "signedAt": { - "type": "integer", - "format": "int64", - "description": "The time in millis when the next driver signed the DVIR on this vehicle.", - "example": 12535500000 - } - } - } - } + "$ref": "#/definitions/DvirBase" } } } @@ -4030,13 +4490,19 @@ "type": "integer", "format": "int64", "description": "ID of the vehicle.", - "example": 112 + "example": 444 + }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" }, "driverId": { "type": "integer", "format": "int64", "description": "ID of the driver.", - "example": 444 + "example": 719 + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "logStartMs": { "type": "integer", @@ -4127,51 +4593,247 @@ } } } - } - } - }, - "ErrorResponse": { - "type": "object", - "description": "Contains the error response when a request fails.", - "properties": { - "status_code": { - "type": "integer", - "description": "HTTP status code returned.", - "format": "int64" - }, - "message": { - "type": "string", - "description": "Error message returned." - } - } - }, - "SensorHistoryResponse": { - "type": "object", - "description": "Contains the results for a sensor history request. Each result contains a timestamp and datapoint for each requested (sensor, field) pair.", - "properties": { - "results": { - "type": "array", - "items": { - "type": "object", - "properties": { - "timeMs": { - "type": "integer", - "description": "Timestamp in UNIX milliseconds.", - "example": 1453449599999 - }, - "series": { - "type": "array", - "description": "List of datapoints, one for each requested (sensor, field) pair.", - "items": { - "type": "integer", - "format": "int64", - "example": 1 - } - } + } + } + }, + "ErrorResponse": { + "type": "object", + "description": "Contains the error response when a request fails.", + "properties": { + "status_code": { + "type": "integer", + "description": "HTTP status code returned.", + "format": "int64" + }, + "message": { + "type": "string", + "description": "Error message returned." + } + } + }, + "SensorHistoryResponse": { + "type": "object", + "description": "Contains the results for a sensor history request. Each result contains a timestamp and datapoint for each requested (sensor, field) pair.", + "properties": { + "results": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timeMs": { + "type": "integer", + "description": "Timestamp in UNIX milliseconds.", + "example": 1453449599999 + }, + "series": { + "type": "array", + "description": "List of datapoints, one for each requested (sensor, field) pair.", + "items": { + "type": "integer", + "format": "int64", + "example": 1 + } + } + } + } + } + } + }, + "DvirBase": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The id of this DVIR record.", + "example": 19 + }, + "timeMs": { + "type": "integer", + "format": "int64", + "description": "Timestamp of this DVIR in UNIX milliseconds.", + "example": 1453449599999 + }, + "inspectionType": { + "type": "string", + "description": "Inspection type of the DVIR.", + "example": "pre trip" + }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" + }, + "vehicleDefects": { + "type": "array", + "description": "Defects registered for the vehicle which was part of the DVIR.", + "items" : { + "type" : "object", + "properties" : { + "defectType": { + "type": "string", + "description": "The type of DVIR defect", + "example": "Air Compressor" + }, + "comment": { + "type": "string", + "description": "The comment describing the type of DVIR defect", + "example": "Air Compressor not working" + } + } + } + }, + "odometerMiles": { + "type": "integer", + "format": "int64", + "description": "The odometer reading in miles for the vehicle when the DVIR was done.", + "example": 49912 + }, + "trailerName": { + "type": "string", + "description": "The name of the trailer which was part of the DVIR.", + "example": "Storer's Trailer 19" + }, + "trailerId": { + "type": "integer", + "description": "The id of the trailer which was part of the DVIR.", + "example": 19 + }, + "trailerDefects": { + "type": "array", + "description": "Defects registered for the trailer which was part of the DVIR.", + "items" : { + "type" : "object", + "properties" : { + "defectType": { + "type": "string", + "description": "The type of DVIR defect", + "example": "Air Compressor" + }, + "comment": { + "type": "string", + "description": "The comment describing the type of DVIR defect", + "example": "Air Compressor not working" + } + } + } + }, + "mechanicNotes": { + "type": "string", + "description": "The mechanics notes on the DVIR.", + "example": "The vehicle is now safe." + }, + "vehicleCondition": { + "type": "string", + "description": "The condition of vechile on which DVIR was done.", + "example": "SATISFACTORY" + }, + "defectsCorrected": { + "type": "boolean", + "description": "Signifies if the defects on the vehicle corrected after the DVIR is done.", + "example": true + }, + "defectsNeedNotBeCorrected": { + "type": "boolean", + "description": "Signifies if the defects on this vehicle can be ignored.", + "example": false + }, + "authorSignature": { + "type": "object", + "description": "The authors signature for the DVIR.", + "properties": { + "type": { + "type": "string", + "description": "Type corresponds to whether the signature corresponds to driver|mechanic.", + "example": "driver" + }, + "name": { + "type": "string", + "description": "The name of the driver or mechanic who signed the DVIR.", + "example": "driver" + }, + "username": { + "type": "string", + "description": "Username of the driver|mechanic who signed the DVIR.", + "example": "driver" + }, + "email": { + "type": "string", + "description": "Email of the driver|mechanic who signed the DVIR.", + "example": "driver" + }, + "signedAt": { + "type": "integer", + "format": "int64", + "description": "The time in millis when the DVIR was signed", + "example": 12535500000 + } + } + }, + "mechanicOrAgentSignature": { + "type": "object", + "description": "The mechanic's or agent's signature for the DVIR.", + "properties": { + "type": { + "type": "string", + "description": "Type corresponds to whether the signature corresponds to driver|mechanic.", + "example": "driver" + }, + "name": { + "type": "string", + "description": "The name of the agent or mechanic who signed the DVIR.", + "example": "driver" + }, + "username": { + "type": "string", + "description": "Username of the agent|mechanic who signed the DVIR.", + "example": "driver" + }, + "email": { + "type": "string", + "description": "Email of the agent|mechanic who signed the DVIR.", + "example": "driver" + }, + "signedAt": { + "type": "integer", + "format": "int64", + "description": "The time in millis when the DVIR was signed", + "example": 12535500000 + } + } + }, + "nextDriverSignature": { + "type": "object", + "description": "The next driver signature for the DVIR.", + "properties": { + "type": { + "type": "string", + "description": "Type corresponds to driver.", + "example": "driver" + }, + "name": { + "type": "string", + "description": "The name of the driver who signed the next DVIR on this vehicle.", + "example": "driver" + }, + "username": { + "type": "string", + "description": "Username of the driver who signed the next DVIR on this vehicle.", + "example": "driver" + }, + "email": { + "type": "string", + "description": "Email of the driver who signed the next DVIR on this vehicle.", + "example": "driver" + }, + "signedAt": { + "type": "integer", + "format": "int64", + "description": "The time in millis when the next driver signed the DVIR on this vehicle.", + "example": 12535500000 } } + } } - } + }, "TaggedVehicleBase": { "type": "object", @@ -4677,16 +5339,16 @@ "example": 55 }, "driver_id": { - "type": "integer", - "format": "int64", - "description": "ID of the driver assigned to the dispatch job.", - "example": 444 + "$ref": "#/definitions/DriverIdResponse" + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "vehicle_id": { - "type": "integer", - "format": "int64", - "description": "ID of the vehicle used for the dispatch job.", - "example": 112 + "$ref": "#/definitions/VehicleIdResponse" + }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" }, "fleet_viewer_url": { "type": "string", @@ -4750,16 +5412,16 @@ ], "properties": { "vehicle_id": { - "type": "integer", - "format": "int64", - "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.", - "example": 444 + "$ref": "#/definitions/VehicleIdResponse" + }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" }, "driver_id": { - "type": "integer", - "format": "int64", - "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.", - "example": 555 + "$ref": "#/definitions/DriverIdResponse" + }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" }, "actual_start_ms": { "type": "integer", @@ -5405,6 +6067,9 @@ "description": "Vehicle associated with the harsh event", "example": 212014918086169 }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" + }, "timestampMs": { "type": "integer", "description": "Timestamp that the harsh event occurred in Unix milliseconds since epoch", @@ -5724,6 +6389,9 @@ "description": "ID of the driver for whom the document is submitted", "example": 555 }, + "driver": { + "$ref": "#/definitions/ExternalDriverResponse" + }, "driverCreatedAtMs": { "type": "integer", "format": "int64", @@ -5739,7 +6407,10 @@ "type": "integer", "format": "int64", "description": "VehicleID of the driver at document creation.", - "example": 222 + "example": 444 + }, + "vehicle": { + "$ref": "#/definitions/ExternalVehicleResponse" }, "fields": { "description": "The fields associated with this document.", @@ -5893,6 +6564,122 @@ "example": "111-222-3344" } } + }, + "UserBase": { + "type": "object", + "properties": { + "name" : { + "type": "string", + "description": "The first and last name of the user.", + "example": "Jane Doe" + }, + "email": { + "type": "string", + "description": "The email address of this user.", + "example": "user@company.com" + }, + "authType": { + "type": "string", + "enum": [ + "basic", + "saml" + ], + "description": "The authentication type the user uses to authenticate. To use SAML this organization must have a configured SAML integration." + }, + "organizationRole" : { + "type": "string", + "description": "The name of the role the user is assigned to for the organization. This will be blank for users that only have access to specific tags.", + "example": "Read-Only Admin" + } + } + }, + "UpsertUserBase": { + "allOf": [ + { + "$ref": "#/definitions/UserBase" + }, + { + "type": "object", + "properties": { + "tagRoles" : { + "type": "array", + "description": "If specified, the user will be a tag administrator for these tags. If left blank, the user has access to the entire organization.", + "items": { + "type": "object", + "properties": { + "tagName": { + "type": "string", + "description": "The name of the tag to grant this user access to.", + "example": "North Carolina Distribution" + }, + "role" : { + "type": "string", + "description": "The name of the role the user is assigned to for this tag. This must match one of the preset roles or the name of a custom role in the organization. This value is case insensitive.", + "example": "Read-Only Admin" + } + } + } + } + } + } + ] + }, + "User": { + "allOf": [ + { + "$ref": "#/definitions/UserBase" + }, + { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The ID of the User record.", + "example": 123 + }, + "tagRoles" : { + "type": "array", + "description": "The specific tags this user has access to. This will be blank for users that have full access to the organization.", + "items": { + "$ref": "#/definitions/UserTagRole" + } + } + } + } + ] + }, + "UserTagRole": { + "type": "object", + "properties": { + "tag": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The ID of this tag.", + "example": 12345 + }, + "name": { + "type": "string", + "description": "Name of this tag.", + "example": "North Carolina Distribution" + }, + "parentTagId": { + "type": "integer", + "format": "int64", + "description": "The ID of this tag.", + "example": 12345 + } + } + }, + "role": { + "type": "string", + "description": "The role the user has been granted on this tag.", + "example": "Full Admin" + } + } } }, "parameters": { @@ -6044,6 +6831,77 @@ "$ref": "#/definitions/DriverForCreate" } }, + "driverParam" : { + "name": "driverParam", + "description": "Driver update body", + "required": true, + "in": "body", + "schema": { + "$ref": "#/definitions/Driver" + } + }, + "createDvirParam": { + "name": "createDvirParam", + "description": "DVIR creation body", + "required": true, + "in": "body", + "schema": { + "type": "object", + "required": [ + "safe", + "inspectionType" + ], + "properties": { + "safe" : { + "type": "string", + "enum": [ + "safe", + "unsafe" + ], + "description": "Whether or not this vehicle or trailer is safe to drive.", + "example": "safe" + }, + "inspectionType": { + "type": "string", + "enum": [ + "mechanic" + ], + "description": "Only type 'mechanic' is currently accepted.", + "example": "mechanic" + }, + "vehicleId" : { + "type": "integer", + "description": "Id of vehicle being inspected. Either vehicleId or trailerId must be provided.", + "example": 10 + }, + "trailerId" : { + "type": "integer", + "description": "Id of trailer being inspected. Either vehicleId or trailerId must be provided.", + "example": 11 + }, + "previousDefectsCorrected": { + "type": "boolean", + "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.", + "example": true + }, + "previousDefectsIgnored": { + "type": "boolean", + "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.", + "example": false + }, + "odometerMiles": { + "type": "integer", + "description": "The current odometer of the vehicle.", + "example": 38426 + }, + "mechanicNotes": { + "type": "string", + "description": "Any notes from the mechanic.", + "example": "Replaced headlight on passenger side." + } + } + } + }, "routeCreateParam": { "name": "createDispatchRouteParams", "required": true, @@ -6242,6 +7100,35 @@ "in": "query", "type": "integer", "format": "int64" + }, + "createUserParam": { + "name": "user", + "description": "User properties. Only one of organizationRole or tagRoles is required.", + "required": true, + "in": "body", + "schema": { + "type": "object", + "required": [ + "name", + "email", + "authType" + ], + "allOf": [ + { + "$ref": "#/definitions/UpsertUserBase" + } + ] + + } + }, + "updateUserParam": { + "name": "user", + "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.", + "required": true, + "in": "body", + "schema": { + "$ref": "#/definitions/UpsertUserBase" + } } } -} +} \ No newline at end of file