Step 14. [V2] Get and update inspection reports.

Steps 13 and 14 are all about maximizing efficiency. Drivers complete daily inspection reports as a part of their compliance workflow. Each inspection report can contain multiple defects. In this step, use the GET method to retrieve inspection reports, and then the PUT method to update an existing report. Additionally, make use of the GET method with the lookup_by_external_id endpoint to retrieve a specific inspection report based on the external ID and integration name.

Use our platform to keep current with inspection reports. Drivers complete daily inspection reports as a part of their compliance workflow.

Daily inspection report records are each tied to both a vehicle and a driver or an asset and a driver. Each inspection report can contain multiple defects.

GET https://api.keeptruckin.com/v2/inspection_reports

Use this method to retrieve both vehicle and asset inspection reports. You can filter your query for inspection reports by providing driver_ids, vehicle_ids, or asset_ids, or by specifying start and end dates for the time window. You can also receive the inspection reports updated after a date using updated_after in the request. Additionally, you can filter by the status of the report

The response includes identifying information for the driver, the reviewer, the vehicle (or asset), the mechanic,. It also introduces the entity_type field, indicating whether the inspection belongs to an asset or a vehicle. The entity_num field provides a unique identifier for the inspected entity. It also returns the inspection_type, indicating whether it is a pre-trip or post-trip inspection, providing additional details about the nature of the inspection. Finally, you can search on reports updated after a specified date.

Furthermore, the response distinguishes between not inspected parts and inspected parts. You can search for reports with the following statuses: all, with_defects, with_no_defects, with_signature_missing. Additionally, depending on if Defect Level Resolution is enabled for your company you can filter with statuses as below,

With Defect Level Resolution -open, resolved or acceptable

Without Defect Level Resolution - unknown, harmless, or corrected

Please note that defects received with type none are parts that were inspected but were found to not have any defect during the driver inspection. The other values for defect type, viz - major, minor, unknown are the ones that contain defects of respective priorities with 'unknown' type reflecting that driver didn't choose to select the defect as major or minor while creating the inspection report.

Note: We only support querying data for 90 days, in a single request

Should an issue in the report get resolved, you can update the report as follows:

PUT https://api.keeptruckin.com/v2/inspection_reports/:id

Use the PUT method to update an existing inspection report. Provide the inspection report id in the URL, and then the report’s new status (this new value can be satisfactory, harmless, or corrected). These updates can come from your system or from a third-party system. Optionally provide your own internal ID for the report, using the external_ids_attributes parameter in your payload.

Additionally, we allow the mechanics/fleet managers to correct/resolve individual defects in a DVIR, removing the need to wait for all the defects to be fixed to update the DVIR. To utilise this defect-level resolution feature, incorporate mechanic details within the defect_statuses parameter of your inspected_parts payload to transmit mechanic details.

Mechanic Details: Provide mechanic_id, mechanic_name, mechanic_note, resolved_defects(list of inspected part ids), and status (which can be open, repaired, or no_repair_needed).

The response includes the entire inspection report for the provided ID, with its updated values.

If Defect Level Resolution is enabled external_resolver_id can be supplied as a request body parameter in defect_statuses. The external_resolver_id serves as an identifier for the resolver within your system. This will be supplied back in Motive's public APIs related to inspection reports only and will not be visible on the dashboard.

Note: If you have Defect Level Resolution enabled, status field passed in PUT API will not update the status of the inspection report and will result in an error as below with 400 http status code.

{error: "inspection report status update is not allowed when defect level resolution is enabled"}

GET https://api.keeptruckin.com/v2/inspection_report/lookup_by_external_id

Use this method to look up a specific inspection report based on an external ID and integration name. Both parameters, external ID and integration name, are required for this operation. Each external ID is uniquely mapped to the corresponding inspection report.

📘

Learn more

Read our reference documentation about the Inspection Report object for details.

Responses based on enabled features

Depending upon the features enabled for your company you will receive variations in the response payload as per the details given below,

If you have *Custom Defect List feature enabled and the driver has used the inspection form with Custom Defect List enabled, you will receive defects object inside every object in inspected_parts array which specifies the type of defect. title specifies the name of the defect selected by the driver for a part, whereas severity defines if the selected defect is a major or minor defect. If any of the defect selected for a part by the driver has severity as major the part will be considered to have a major defect.

If you have Defect Level Resolution feature enabled you will receive mechanic_details in objects inside theinspected_parts array along with the status of the part. Please note mechanic_signature_url and mechanic_signed_at values at the inspection_report object level will be null, since the mechanic details are contained inside every inspected_part. The status of a part can be one of these values open, repaired, no_repair_needed and good. Also note that, you will receive resolver object inside the mechanic_details object and a mechanic_name inside mechanic_details separately, here mechanic object specifies the logged in user(dispatcher/fleet manager) where as mechanic_name is the name entered(could be different from the logged in user) while resolving the defect.

If you have Defect Level Resolution enabled, the external_resolver_id serves as an identifier for the resolver within your system. This will be supplied back in Motive's public APIs related to inspection reports only and will not be visible on the dashboard.

{
  "inspection_reports": [
    {
      "inspection_report": {
        "id": 9,
        "log_id": 1,
        "date": "2016-07-22",
        "time": "2016-07-22T14:00:00Z",
        "odometer": 253,
        "carrier_name": "Demo Carrier",
        "location": "Omaha, NE",
        "status": "corrected",
        "mechanic_signed_at": "2016-07-22T14:00:00Z",
        "mechanic_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/mechanic_signature_upload/9/open-uri20160712-30633-thc30n?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "driver_signed_at": "2016-07-22T14:00:00Z",
        "driver_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/driver_signature_upload/9/open-uri20160729-30645-1jeoj77?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "reviewer_signed_at": "2016-07-22T14:00:00Z",
        "reviewer_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/reviewer_signature_upload/9/open-uri20160729-30645-1jeoj77?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "entity_num": "entity_num",
        "entity_type": "vehicle",
        "is_rejected": false,
        "inspection_type": "pre-trip",
        "declaration": "I declare that this vehicle has been inspected in accordance with the applicable requirements.",
        "inspected_parts": [
          {
            "id": 5,
            "category": "Brakes",
            "notes": "notes",
            "type": "major",
            "picture_url": "https://keep-truckin-preview.s3.amazonaws.com/uploads/defect/picture_upload/23137/15c31555-6642-4215-a3cd-81def1d329012396939324379336808.jpg?X"
          }
        ],
        "not_inspected_parts": [
          {
            "category": "9 - Emergency Equipment & Safety Devices"
          },
          {
            "category": "15 - Heater/Defroster"
          }
        ],
        "vehicle": {
          "id": 4,
          "number": "Demo Vehicle",
          "year": "2016",
          "make": "Demo",
          "model": "Vehicle",
          "vin": "WP0AB2966NS458669",
          "metric_units": false
        },
        "asset": {
          "id": 101,
          "make": "Toyota",
          "metric_units": true,
          "model": "Camry",
          "name": "V123",
          "year": 2022
        },
        "mechanic": {
          "id": 12,
          "first_name": "Joe",
          "last_name": "Williams",
          "username": null,
          "email": "[email protected]",
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "driver": {
          "id": 11,
          "first_name": "Demo",
          "last_name": "Driver",
          "username": "demo_driver",
          "email": null,
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "reviewer": {
          "id": 13,
          "first_name": "John",
          "last_name": "Williams",
          "username": null,
          "email": "[email protected]",
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "external_ids": [
          {
            "external_id": "201",
            "integration_name": "generic_tms"
          },
          {
            "external_id": "Truck123",
            "integration_name": "generic_maintenance_system"
          }
        ],
        "entries": [
          {
            "name": "Tractor Plate #",
            "value": "2743186",
            "position": 1
          },
          {
            "name": "Trailer Plate #",
            "value": "T473278",
            "position": 2
          }
        ]
      }
    }
  ],
  "per_page": 25,
  "page_no": 1,
  "total": 3
}
{
  "inspection_reports": [
    {
      "inspection_report": {
        "id": 9,
        "log_id": 1,
        "date": "2016-07-22",
        "time": "2016-07-22T14:00:00Z",
        "odometer": 253,
        "carrier_name": "Demo Carrier",
        "location": "Omaha, NE",
        "status": "corrected",
        "mechanic_signed_at": "2016-07-22T14:00:00Z",
        "mechanic_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/mechanic_signature_upload/9/open-uri20160712-30633-thc30n?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "driver_signed_at": "2016-07-22T14:00:00Z",
        "driver_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/driver_signature_upload/9/open-uri20160729-30645-1jeoj77?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "reviewer_signed_at": "2016-07-22T14:00:00Z",
        "reviewer_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/reviewer_signature_upload/9/open-uri20160729-30645-1jeoj77?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "entity_num": "entity_num",
        "entity_type": "vehicle",
        "is_rejected": false,
        "inspection_type": "pre-trip",
        "declaration": "I declare that this vehicle has been inspected in accordance with the applicable requirements.",
        "inspected_parts": [
          {
            "id": 5,
            "category": "Brakes",
            "notes": "notes",
            "type": "major",
            "picture_url": "https://keep-truckin-preview.s3.amazonaws.com/uploads/defect/picture_upload/23137/15c31555-6642-4215-a3cd-81def1d329012396939324379336808.jpg",
            "defects": [
              {
                "title": "Air pressure gauge failure",
                "severity": "major"
              },
              {
                "title": "Slow air pressure build up rate",
                "severity": "major"
              },
              {
                "title": "Air loss rate exceeds prescribed limit",
                "severity": "minor"
              }
            ]
          }
        ],
        "not_inspected_parts": [
          {
            "category": "9 - Emergency Equipment & Safety Devices"
          },
          {
            "category": "15 - Heater/Defroster"
          }
        ],
        "vehicle": {
          "id": 4,
          "number": "Demo Vehicle",
          "year": "2016",
          "make": "Demo",
          "model": "Vehicle",
          "vin": "WP0AB2966NS458669",
          "metric_units": false
        },
        "asset": {
          "id": 101,
          "make": "Toyota",
          "metric_units": true,
          "model": "Camry",
          "name": "V123",
          "year": 2022
        },
        "mechanic": {
          "id": 12,
          "first_name": "Joe",
          "last_name": "Williams",
          "username": null,
          "email": "[email protected]",
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "driver": {
          "id": 11,
          "first_name": "Demo",
          "last_name": "Driver",
          "username": "demo_driver",
          "email": null,
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "reviewer": {
          "id": 13,
          "first_name": "John",
          "last_name": "Williams",
          "username": null,
          "email": "[email protected]",
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "external_ids": [
          {
            "external_id": "201",
            "integration_name": "generic_tms"
          },
          {
            "external_id": "Truck123",
            "integration_name": "generic_maintenance_system"
          }
        ],
        "entries": [
          {
            "name": "Tractor Plate #",
            "value": "2743186",
            "position": 1
          },
          {
            "name": "Trailer Plate #",
            "value": "T473278",
            "position": 2
          }
        ]
      }
    }
  ],
  "per_page": 25,
  "page_no": 1,
  "total": 3
}
{
  "inspection_reports": [
    {
      "inspection_report": {
        "id": 9,
        "log_id": 1,
        "date": "2016-07-22",
        "time": "2016-07-22T14:00:00Z",
        "odometer": 253,
        "carrier_name": "Demo Carrier",
        "location": "Omaha, NE",
        "status": "resolved",
        "mechanic_signed_at": null,
        "mechanic_signature_url": null,
        "driver_signed_at": "2016-07-22T14:00:00Z",
        "driver_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/driver_signature_upload/9/open-uri20160729-30645-1jeoj77?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "reviewer_signed_at": "2016-07-22T14:00:00Z",
        "reviewer_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/reviewer_signature_upload/9/open-uri20160729-30645-1jeoj77?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "entity_num": "entity_num",
        "entity_type": "vehicle",
        "is_rejected": false,
        "inspection_type": "pre-trip",
        "declaration": "I declare that this vehicle has been inspected in accordance with the applicable requirements.",
        "inspected_parts": [
          {
            "id": 5,
            "category": "Brakes",
            "notes": "notes",
            "type": "major",
            "picture_url": "https://keep-truckin-preview.s3.amazonaws.com/uploads/defect/picture_upload/23137/15c31555-6642-4215-a3cd-81def1d329012396939324379336808.jpg?X",
            "status": "[open]/[repaired]/[no_repair_needed]/[good]",
            "mechanic_details": {
              "resolver": {
                "id": 1005,
                "first_name": "Joshua",
                "last_name": "Lee",
                "username": "Joshua Lee",
                "email": "[email protected]",
                "driver_company_id": "123",
                "status": "active",
                "role": "driver"
              },
              "external_resolver_id": "111",
              "mechanic_name": "Joshua Lee",
              "mechanic_signed_at": "2016-07-22T14:00:00Z",
              "mechanic_note": "this is resolved person note, could be anything",
              "mechanic_signature": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/mechanic_signature_upload/9/open-uri20160712-30633-thc30n?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D"
            }
          }
        ],
        "not_inspected_parts": [
          {
            "category": "9 - Emergency Equipment & Safety Devices"
          },
          {
            "category": "15 - Heater/Defroster"
          }
        ],
        "vehicle": {
          "id": 4,
          "number": "Demo Vehicle",
          "year": "2016",
          "make": "Demo",
          "model": "Vehicle",
          "vin": "WP0AB2966NS458669",
          "metric_units": false
        },
        "asset": {
          "id": 101,
          "make": "Toyota",
          "metric_units": true,
          "model": "Camry",
          "name": "V123",
          "year": 2022
        },
        "mechanic": {
          "id": 12,
          "first_name": "Joe",
          "last_name": "Williams",
          "username": null,
          "email": "[email protected]",
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "driver": {
          "id": 11,
          "first_name": "Demo",
          "last_name": "Driver",
          "username": "demo_driver",
          "email": null,
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "reviewer": {
          "id": 13,
          "first_name": "John",
          "last_name": "Williams",
          "username": null,
          "email": "[email protected]",
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "external_ids": [
          {
            "external_id": "201",
            "integration_name": "generic_tms"
          },
          {
            "external_id": "Truck123",
            "integration_name": "generic_maintenance_system"
          }
        ],
        "entries": [
          {
            "name": "Tractor Plate #",
            "value": "2743186",
            "position": 1
          },
          {
            "name": "Trailer Plate #",
            "value": "T473278",
            "position": 2
          }
        ]
      }
    }
  ],
  "per_page": 25,
  "page_no": 1,
  "total": 3
}
{
  "inspection_reports": [
    {
      "inspection_report": {
        "id": 9,
        "log_id": 1,
        "date": "2016-07-22",
        "time": "2016-07-22T14:00:00Z",
        "odometer": 253,
        "carrier_name": "Demo Carrier",
        "location": "Omaha, NE",
        "status": "resolved",
        "mechanic_signed_at": null,
        "mechanic_signature_url": null,
        "driver_signed_at": "2016-07-22T14:00:00Z",
        "driver_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/driver_signature_upload/9/open-uri20160729-30645-1jeoj77?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "reviewer_signed_at": "2016-07-22T14:00:00Z",
        "reviewer_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/reviewer_signature_upload/9/open-uri20160729-30645-1jeoj77?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "entity_num": "entity_num",
        "entity_type": "vehicle",
        "is_rejected": false,
        "inspection_type": "pre-trip",
        "declaration": "I declare that this vehicle has been inspected in accordance with the applicable requirements.",
        "inspected_parts": [
          {
            "id": 5,
            "category": "Brakes",
            "notes": "notes",
            "type": "major",
            "picture_url": "https://keep-truckin-preview.s3.amazonaws.com/uploads/defect/picture_upload/23137/15c31555-6642-4215-a3cd-81def1d329012396939324379336808.jpg?X",
            "status": "[open]/[repaired]/[no_repair_needed]/[good]",
            "mechanic_details": {
              "resolver": {
                "id": 1005,
                "first_name": "Joshua",
                "last_name": "Lee",
                "username": "Joshua Lee",
                "email": "[email protected]",
                "driver_company_id": "123",
                "status": "active",
                "role": "driver"
              },
              "external_resolver_id": "111",
              "mechanic_name": "Joshua Lee",
              "mechanic_signed_at": "2016-07-22T14:00:00Z",
              "mechanic_note": "this is resolved person note, could be anything",
              "mechanic_signature": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/mechanic_signature_upload/9/open-uri20160712-30633-thc30n?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D"
            },
            "defects": [
              {
                "title": "Air pressure gauge failure",
                "severity": "major"
              },
              {
                "title": "Slow air pressure build up rate",
                "severity": "major"
              },
              {
                "title": "Air loss rate exceeds prescribed limit",
                "severity": "minor"
              }
            ]
          }
        ],
        "not_inspected_parts": [
          {
            "category": "9 - Emergency Equipment & Safety Devices"
          },
          {
            "category": "15 - Heater/Defroster"
          }
        ],
        "vehicle": {
          "id": 4,
          "number": "Demo Vehicle",
          "year": "2016",
          "make": "Demo",
          "model": "Vehicle",
          "vin": "WP0AB2966NS458669",
          "metric_units": false
        },
        "asset": {
          "id": 101,
          "make": "Toyota",
          "metric_units": true,
          "model": "Camry",
          "name": "V123",
          "year": 2022
        },
        "mechanic": {
          "id": 12,
          "first_name": "Joe",
          "last_name": "Williams",
          "username": null,
          "email": "[email protected]",
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "driver": {
          "id": 11,
          "first_name": "Demo",
          "last_name": "Driver",
          "username": "demo_driver",
          "email": null,
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "reviewer": {
          "id": 13,
          "first_name": "John",
          "last_name": "Williams",
          "username": null,
          "email": "[email protected]",
          "driver_company_id": "123",
          "mcleod_id": null,
          "status": "active",
          "role": "driver"
        },
        "external_ids": [
          {
            "external_id": "201",
            "integration_name": "generic_tms"
          },
          {
            "external_id": "Truck123",
            "integration_name": "generic_maintenance_system"
          }
        ],
        "entries": [
          {
            "name": "Tractor Plate #",
            "value": "2743186",
            "position": 1
          },
          {
            "name": "Trailer Plate #",
            "value": "T473278",
            "position": 2
          }
        ]
      }
    }
  ],
  "per_page": 25,
  "page_no": 1,
  "total": 3
}
Language
Authorization
Header
Click Try It! to start a request and see the response here!