Guides
SUPPORTFEEDBACK

Driver Vehicle Inspection Reports

Suggest Edits

Overview

Driver Vehicle Inspection Reports (DVIRs) can be created and managed through the Samsara cloud dashboard, the Samsara Driver App, and the Samsara REST API.

DVIRs can be created by drivers or mechanics. Driver DVIRs are submitted through the Samsara Driver App. Mechanic DVIRs are submitted through the cloud dashboard, or they can be created via the REST API.

All DVIRs follow the following life cycle:

  1. A DVIR is created as either safe or unsafe. Both safe and unsafe DVIRs may contain zero or more defects. The DVIR is signed by whoever created it.
  2. The DVIR's defects may be resolved with further inspections. Not all defects need to be resolved at once. When a defect is resolved, its status is updated to indicate the mechanic that resolved the defect.
  3. An unsafe DVIR will eventually be resolved. When resolved, the DVIR will be updated with a second signature of the person who resolved it.
  4. If a new, safe DVIR is created for the same vehicle, the resolved DVIR will be updated with a third signature indicating the vehicle was safe to drive after its repairs.

See the Maintenance API docs for full details on the DVIRs REST APIs.

Listing DVIRs

The Get all DVIRs endpoint allows you to retrieve all DVIRs that were created during a given time period.

This endpoint returns the current state of the DVIRs that were created during the given time range. Subsequent requests (using the same time parameters) allow you to "refresh" the data and receive the new state of the DVIRs if any changes were made.

Here's an example request:

curl --request GET 'https://api.samsara.com/fleet/dvirs/history?startTime=2020-10-15T00:00:00Z&endTime=2020-11-01T00:00:00Z' \
--header 'Authorization: Bearer <<token>>'

The JSON response will contain a data array, where each entry in the array is a DVIR that was created during the requested time range. If there are many DVIRs to return, the response may be paginated:

{
    "data": [
        {
            "id": "57658816",
            "authorSignature": {
                "signatoryUser": {
                    "id": "1654973",
                    "name": "Driver Danielle"
                },
                "signedAtTime": "2020-10-30T20:34:34.000Z",
                "type": "driver"
            },
            "secondSignature": {
                "signatoryUser": {
                    "id": "75885",
                    "name": "Mechanic Matthew"
                },
                "signedAtTime": "2020-10-30T20:34:53.424Z",
                "type": "mechanic"
            },
            "thirdSignature": {
                "signatoryUser": {
                    "id": "16549734",
                    "name": "Driver Dave"
                },
                "signedAtTime": "2020-10-30T20:44:21.000Z",
                "type": "driver"
            },
            "safetyStatus": "safe",
            "startTime": "2020-10-30T20:34:21.151Z",
            "endTime": "2020-10-30T20:34:34.000Z",
            "type": "preTrip",
            "odometerMeters": 241079296,
            "licensePlate": "6KDB798",
            "location": "Berry Street, San Francisco, CA",
            "vehicle": {
                "id": "281474977075805",
                "name": "Little Red"
            },
            "vehicleDefects": [
                {
                    "id": "2728665",
                    "isResolved": true,
                    "defectType": "Battery",
                    "createdAtTime": "2020-10-30T20:34:21.151Z",
                    "resolvedAtTime": "2020-10-30T20:34:53.424Z",
                    "resolvedBy": {
                        "id": "75885",
                        "name": "Mechanic Matthew",
                        "type": "mechanic"
                    },
                    "vehicle": {
                        "id": "281474977075805",
                        "name": "Little Red"
                    },
                    "mechanicNotesUpdatedAtTime": "2020-10-30T20:34:53.436Z"
                }
            ]
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

The DVIR returned in the example above has gone through a complete lifecycle.

The authorSignature indicates that the DVIR was created by a driver. The driver's id and name are included in the signatoryUser field. You can use the Drivers API to get more details on the driver.

The secondSignature indicates that the DVIR was resolved by a mechanic. The mechanic's id and name are included in the signatoryUser field. You can use the Users API to get more details on the mechanic.

The thirdSignature indicates that the DVIR was inspected again by a driver. The driver's id and name are included in the signatoryUser field. You can use the Drivers API to get more details on the driver.

The safetyStatus indicates that the vehicle is currently marked as safe.

The DVIR type indicates that this DVIR was originally a preTrip DVIR.

The vehicleDefects array shows that there was one defect, which has now been resolved. The resolvedBy field indicates the mechanic that resolved this defect. You can use the Users API to get more details on the mechanic.

See the Get all DVIRs reference docs for full details on DVIR response body fields.

Listing Defects

If you want to retrieve a list of just DVIR defects, you can use the Get all defects endpoint. This endpoint returns all defects that were created during a given time period. To see the full DVIRs that these defects get reported in, see the Listing DVIRs section.

This endpoint returns the current state of the defects that were created during the given time range. Subsequent requests (using the same time parameters) allow you to "refresh" the data and receive the new state of the defects if any changes were made.

Here's an example request:

curl --request GET 'https://api.samsara.com/fleet/defects/history?startTime=2020-10-15T00:00:00Z&endTime=2020-11-01T00:00:00Z' \
--header 'Authorization: Bearer <<token>>'

The JSON response will contain a data array, where each entry in the array is a defect that was created during the requested time period. If there are many defects to return, the response may be paginated:

{
    "data": [
        {
            "id": "2728665",
            "isResolved": true,
            "defectType": "Battery",
            "createdAtTime": "2020-10-30T20:34:21.151Z",
            "resolvedAtTime": "2020-10-30T20:34:53.424Z",
            "resolvedBy": {
                "id": "75885",
                "name": "Tyler Freckmann",
                "type": "mechanic"
            },
            "vehicle": {
                "id": "281474977075805",
                "name": "Little Red"
            },
            "mechanicNotesUpdatedAtTime": "2020-10-30T20:34:53.436Z"
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

The defect returned in the example above has gone has been resolved.

The resolvedBy field indicates the mechanic that resolved this defect. You can use the Users API to get more details on the mechanic.

See the Get all defects reference docs for full details on response body fields.

Resolving DVIRs

You can use the API to resolve DVIRs on behalf of a mechanic using the Resolve a DVIR endpoint.

You can retrieve a list of DVIRs created during a specific time range using the Listing DVIRs endpoint. This will return a list of DVIRs, each with an id and safetyStatus.

In order to resolve a DVIR via the API, the DVIR's safetyStatus must be unsafe.

To resolve a DVIR, submit a request to the following API endpoint, providing the DVIR's id as a URL path parameter:

PATCH https://api.samsara.com/fleet/dvirs/:id

You must submit a JSON request body. The authorId field will be the ID of the mechanic that you are resolving the DVIR on behalf of. This will be the ID of a Samsara dashboard user. See the Users API for more details. You must also set the isResolved field to true. Additionally, you may also provide resolution notes in the optional mechanicNotes field.

Example request body:

{
    "authorId": "75885",
    "isResolved": true,
    "mechanicNotes": "This DVIR is now resolved."
}

See the Resolve a DVIR reference docs for full request and response body details.

Resolving Defects

You can use the API to directly resolve defects on behalf of a mechanic using the Update a defect endpoint.

You can retrieve a list of defects created during a specific time range using the Listing Defects endpoint. This will return a list of defects, each with an id an isResolved field. Additionally, defects and their resolution status are also included in the vehicleDefects array on DVIRs.

You cannot update defects that have already been resolved. In order to resolve a defect via the API, the defect's isResolved field be false.

To resolve a defect, submit a request to the following API endpoint, providing the defect's id as a URL path parameter:

PATCH https://api.samsara.com/fleet/defects/:id

You must submit a JSON request body. The isResolved field must be set to true. The resolvedBy field should indicate the mechanic that you are resolving the defect on behalf of. This will be a Samsara dashboard user. The id should be a valid Samsara dashboard user's ID. See the Users API for more details. type must be set to mechanic. Additionally, you may also provide resolution notes in the optional mechanicNotes field.

Example request body:

{
    "isResolved": true,
    "resolvedBy": {
        "id": "75885",
        "type": "mechanic"
    },
    "mechanicNotes": "Defect is resolved."
}

See the Update a defect reference docs for full request and response body details.

Creating a DVIR

You can use the API to create a DVIR on behalf of a mechanic using the Create a mechanic DVIR endpoint.

curl --request POST 'https://api.samsara.com/fleet/dvirs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<token>>' \

You must submit a JSON request body. The safetyStatus may be safe or unsafe. The type of the DVIR must be set to mechanic. The authorId field will be the ID of the mechanic that you are resolving the DVIR on behalf of. This will be the ID of a Samsara dashboard user. See the Users API for more details. The vehicleId will be the ID of the vehicle for this DVIR. You may optionally include mechanicNotes with this DVIR. If not provided, odometerMeters will default to 0 on the DVIR.

Example request body:

{
    "safetyStatus": "safe",
    "type": "mechanic",
    "authorId": "75885",
    "mechanicNotes": "This vehicle is safe to drive.",
    "odometerMeters": 241079296,
    "vehicleId": "281474977075805"
}

See the Create a mechanic DVIR reference docs for full request and response body details.

Updated almost 4 years ago