Samsara Dvirs API
The Dvirs API from Samsara — 3 operation(s) for dvirs.
OpenAPI Specification
openapi: 3.0.1
info:
description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
title: Samsara Dvirs API
version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Dvirs
paths:
/fleet/dvirs:
post:
description: "Creates a new mechanic DVIR in the organization. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Write DVIRs** under the Maintenance category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: createDvir
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDvirRequest'
description: The DVIR to create.
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DvirResponse'
description: Newly created DVIR.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: Create a Mechanic DVIR
tags:
- Dvirs
x-codegen-request-body-name: dvir
/fleet/dvirs/history:
get:
description: "Returns a list of all DVIRs in an organization. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Read DVIRs** under the Maintenance category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: getDvirHistory
parameters:
- description: The limit for how many objects will be in the response. Default and max for this value is 512 objects.
in: query
name: limit
schema:
format: int64
maximum: 512
minimum: 1
type: integer
- description: If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
in: query
name: after
schema:
type: string
- description: 'A filter on the data based on this comma-separated list of parent tag IDs, for use by orgs with tag hierarchies. Specifying a parent tag will implicitly include all descendent tags of the parent tag. Example: `parentTagIds=345,678`'
explode: false
in: query
name: parentTagIds
schema:
items:
type: string
type: array
style: form
- description: 'A filter on the data based on this comma-separated list of tag IDs. Example: `tagIds=1234,5678`'
explode: false
in: query
name: tagIds
schema:
items:
type: string
type: array
style: form
- description: 'A start time in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
in: query
name: startTime
required: true
schema:
type: string
- description: 'An end time in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
in: query
name: endTime
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DvirsListResponse'
description: List of all DVIRs in the organization
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: Get All DVIRs
tags:
- Dvirs
/fleet/dvirs/{id}:
patch:
description: "Resolves a given DVIR by marking its `isResolved` field to `true`. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Write DVIRs** under the Maintenance category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: updateDvir
parameters:
- description: ID of the DVIR.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDvirRequest'
description: The dvir fields to update.
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DvirResponse'
description: Updated dvir object with ID.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: Resolve a DVIR
tags:
- Dvirs
x-codegen-request-body-name: dvir
components:
schemas:
DvirVehicle:
allOf:
- description: The vehicle the DVIR was submitted for. Only included for tractor or tractor+trailer DVIRs.
type: object
- $ref: '#/components/schemas/vehicleTinyResponse'
CreateDvirRequest:
description: DVIR creation body
properties:
authorId:
description: Samsara user ID of the mechanic creating the DVIR.
example: '11'
type: string
licensePlate:
description: The license plate of this vehicle.
example: XHK1234
maxLength: 12
type: string
location:
description: Optional string if your jurisdiction requires a location of the DVIR.
example: 350 Rhode Island St Ste. 400S, San Francisco, CA 94103
type: string
mechanicNotes:
description: The mechanics notes on the DVIR.
example: Replaced headlight on passenger side.
type: string
odometerMeters:
description: The odometer reading in meters.
example: 14010293
type: integer
resolvedDefectIds:
description: Array of ids for defects being resolved with this DVIR.
items:
type: string
type: array
safetyStatus:
description: Whether or not this vehicle or trailer is safe to drive.
enum:
- safe
- unsafe
example: safe
type: string
trailerId:
description: Id of trailer being inspected. Either vehicleId or trailerId must be provided.
example: '11'
type: string
type:
description: Only type 'mechanic' is currently accepted.
enum:
- mechanic
example: mechanic
type: string
vehicleId:
description: Id of vehicle being inspected. Either vehicleId or trailerId must be provided.
example: '10'
type: string
required:
- authorId
- safetyStatus
- type
type: object
DvirsListResponse:
description: A list of DVIRs and pagination information.
properties:
data:
description: A list of DVIRs.
items:
$ref: '#/components/schemas/Dvir'
type: array
pagination:
$ref: '#/components/schemas/paginationResponse'
required:
- data
- pagination
type: object
DvirSignature:
description: DVIR Signure.
properties:
signatoryUser:
allOf:
- description: The user who signed the DVIR.
type: object
- $ref: '#/components/schemas/userTinyResponse'
type: object
signedAtTime:
description: 'The time when the DVIR was signed. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
example: '2020-01-27T07:06:25Z'
type: string
type:
default: driver
description: 'Whether the DVIR was submitted by a `driver` or `mechanic`. Valid values: `driver`, `mechanic`.'
enum:
- driver
- mechanic
example: driver
type: string
type: object
vehicleTinyResponse:
description: A minified vehicle object.
properties:
ExternalIds:
additionalProperties:
type: string
description: The [external IDs](https://developers.samsara.com/docs/external-ids) for the given object.
example:
maintenanceId: '250020'
payrollId: ABFS18600
type: object
id:
description: ID of the vehicle.
example: '123456789'
type: string
name:
description: Name of the vehicle.
example: 'Midwest Truck #4'
type: string
type: object
DvirVehicleDefects:
description: Defects registered for the vehicle which was part of the DVIR.
items:
$ref: '#/components/schemas/dvirTrailerDefectsItems'
type: array
standardErrorResponse:
description: Error response
properties:
message:
description: The message of the error.
example: An error has occurred.
type: string
requestId:
description: The ID of the request.
example: 8916e1c1
type: string
type: object
DvirTrailerDefects:
description: Defects registered for the trailer which was part of the DVIR.
items:
$ref: '#/components/schemas/dvirTrailerDefectsItems'
type: array
DvirSecondSignature:
allOf:
- description: An author signature object which has a signatory mini object with the signed time. Second Signature.
type: object
- $ref: '#/components/schemas/DvirSignature'
DvirLicensePlate:
description: The license plate of this vehicle.
example: XHK1234
maxLength: 12
type: string
dvirTrailerDefectsItems:
properties:
comment:
description: Comment on the defect.
example: Air Compressor not working
type: string
createdAtTime:
description: 'Time when the defect was created. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
example: '2020-01-27T07:06:25Z'
type: string
defectType:
description: The type of DVIR defect.
example: Air Compressor
type: string
id:
description: ID of the defect.
example: '18'
type: string
isResolved:
description: Signifies if this defect is resolved.
example: true
type: boolean
mechanicNotes:
description: The mechanics notes on the defect.
example: Extremely large oddly shaped hole in passenger side window.
type: string
mechanicNotesUpdatedAtTime:
description: 'Time when mechanic notes were last updated. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
example: '2020-01-27T07:06:25Z'
type: string
resolvedAtTime:
description: 'Time when this defect was resolved. Will not be returned if the defect is unresolved. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
example: '2020-01-27T07:06:25Z'
type: string
resolvedBy:
$ref: '#/components/schemas/Defect_resolvedBy'
trailer:
allOf:
- description: The trailer this defect was submitted for.
type: object
- description: A minified trailer object.
properties:
id:
description: ID of the trailer.
example: '123456789'
type: string
name:
description: Name of the trailer.
example: 'Midwest Trailer #5'
type: string
type: object
type: object
vehicle:
allOf:
- description: The vehicle this defect was submitted for.
type: object
- description: A minified vehicle object.
properties:
ExternalIds:
additionalProperties:
type: string
description: The [external IDs](https://developers.samsara.com/docs/external-ids) for the given object.
example:
maintenanceId: '250020'
payrollId: ABFS18600
type: object
id:
description: ID of the vehicle.
example: '123456789'
type: string
name:
description: Name of the vehicle.
example: 'Midwest Truck #4'
type: string
type: object
type: object
required:
- id
- isResolved
type: object
x-go-gen-location: models
Defect_resolvedBy:
description: The person who resolved this defect. Will not be returned if the defect is unresolved.
properties:
id:
description: ID of the entity that resolved this defect. If the defect was resolved by a driver, this will be a Samsara Driver ID. If the defect was resolved by a mechanic, this will be the Samsara Dashboard User ID of the mechanic.
example: '11'
type: string
name:
description: Name of the person who resolved this defect.
example: Christopher 'The Handyman' Zhen
type: string
type:
description: Indicates whether this defect was resolved by a `driver` or a `mechanic`.
enum:
- driver
- mechanic
type: string
type: object
userTinyResponse:
description: A minified user object.
properties:
id:
description: ID of the user.
example: '88668'
type: string
name:
description: Name of the user.
example: Susan Bob
type: string
type: object
trailerTinyResponse:
description: A minified trailer object.
properties:
id:
description: ID of the trailer.
example: '123456789'
type: string
name:
description: Name of the trailer.
example: 'Midwest Trailer #5'
type: string
type: object
UpdateDvirRequest:
description: Information about resolving a DVIR.
properties:
authorId:
description: The user who is resolving the dvir.
example: '11'
type: string
isResolved:
description: Resolves the DVIR. Must be `true`.
type: boolean
mechanicNotes:
description: The mechanics notes on the DVIR.
example: Replaced headlight on passenger side.
type: string
signedAtTime:
description: 'Time when user signed this DVIR. Defaults to now. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
example: '2020-01-27T07:06:25Z'
type: string
required:
- authorId
- isResolved
type: object
DvirAuthorSignature:
allOf:
- description: An author signature object which has a signatory mini object with the signed time. Author Signature.
type: object
- $ref: '#/components/schemas/DvirSignature'
DvirTrailer:
allOf:
- description: The trailer the DVIR was submitted for. Only included for trailer only DVIRs.
type: object
- $ref: '#/components/schemas/trailerTinyResponse'
DvirOdometerMeters:
description: The odometer reading in meters.
example: 14010293
type: integer
DvirLocation:
description: Optional string if your jurisdiction requires a location of the DVIR.
example: 350 Rhode Island St Ste. 400S, San Francisco, CA 94103
type: string
DvirThirdSignature:
allOf:
- description: An author signature object which has a signatory mini object with the signed time. Third Signature.
type: object
- $ref: '#/components/schemas/DvirSignature'
paginationResponse:
description: Pagination parameters.
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.
example: MjkY
format: string
type: string
hasNextPage:
description: True if there are more pages of results immediately available after this endCursor.
example: true
type: boolean
required:
- endCursor
- hasNextPage
type: object
DvirResponse:
description: The DVIR response.
properties:
data:
$ref: '#/components/schemas/Dvir'
type: object
Dvir:
description: Information about a DVIR.
properties:
authorSignature:
$ref: '#/components/schemas/DvirAuthorSignature'
endTime:
description: 'Time when driver signed and completed this DVIR. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
example: '2020-01-27T07:06:25Z'
type: string
id:
description: Unique Samsara ID for the DVIR.
example: '7107471'
type: string
licensePlate:
$ref: '#/components/schemas/DvirLicensePlate'
location:
$ref: '#/components/schemas/DvirLocation'
mechanicNotes:
$ref: '#/components/schemas/DvirMechanicNotes'
odometerMeters:
$ref: '#/components/schemas/DvirOdometerMeters'
safetyStatus:
default: unsafe
description: 'The condition of vehicle on which DVIR was done. Valid values: `safe`, `unsafe`, `resolved`.'
enum:
- safe
- unsafe
- resolved
example: unsafe
type: string
secondSignature:
$ref: '#/components/schemas/DvirSecondSignature'
startTime:
description: 'Time when driver began filling out this DVIR. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
example: '2020-01-27T07:06:25Z'
type: string
thirdSignature:
$ref: '#/components/schemas/DvirThirdSignature'
trailer:
$ref: '#/components/schemas/DvirTrailer'
trailerDefects:
$ref: '#/components/schemas/DvirTrailerDefects'
trailerName:
description: The name of the trailer the DVIR was submitted for. Only included for tractor+trailer DVIRs.
example: 'Midwest Trailer #5'
type: string
type:
default: unspecified
description: 'Inspection type of the DVIR. Valid values: `preTrip`, `postTrip`, `mechanic`, `unspecified`.'
enum:
- preTrip
- postTrip
- mechanic
- unspecified
example: preTrip
type: string
vehicle:
$ref: '#/components/schemas/DvirVehicle'
vehicleDefects:
$ref: '#/components/schemas/DvirVehicleDefects'
required:
- id
type: object
DvirMechanicNotes:
description: The mechanics notes on the DVIR.
example: Replaced headlight on passenger side.
type: string
securitySchemes:
AccessTokenHeader:
type: http
scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
explorer-enabled: true
proxy-enabled: true