The DVIR Forms V3 API is used to handle queries for creation and editing DVIR forms similar to that of the DVIR Forms API. The difference between the V3 and the V2 APIs is that the V3 API accepts and returns only inspection points that either marked as failed, have a comment, or have an image attached to it. Inspections that all items marked as passed and do not have comments or images will still appear in this API but will have an empty “points” array in their DVIR Area. A “templateId” field is required to construct the complete form with both PASSED and FAILED inspection points.
DVIR Form Inspections are automatically deleted after a specific period of time following the data retention policy.
Fields
| Tag | Data Type | Required | Description |
| accountId | Long | Auto | The id of the Account that owns this record. |
| areas | Array | No | The areas of the DVIR Form |
| description | Text (unlimited) | No | A description of the DVIR Form |
| dvirId | Long | No | The ID of the DVIR where this inspection belonged to. Value is 0 if the inspection has not yet been included in a DVIR record. |
| endTime * | Text | No | Timestamp when the inspection ended Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z) |
| equipmentCondition * | Condition of the Equipment according to the DVIR. Can either be:
|
||
| equipmentId | Long | No | Id of the Equipment associated with the DVIR record |
| id | Auto-incremented Long | Auto | Unique identifier |
| inspectionType * | inspection_trip_type | No | Information on the type of inspection. Can either be:
|
| inspectorType * | inspector_type | No | Information on the type of inspector. Can either be:
|
| isTemplate | Boolean | No | Indicates if the record is a DVIR form (true) or an inspection (false) |
| location * | Character (255) | No | The address where the DVIR was performed. |
| media | Array | No | Image associated with the DVIR Form, usually a picture of Equipment |
| name | Character (255) | Yes | The name of the DVIR Form |
| odometerKm* | Double Precision | No | The odometer value on the time of the DVIR. Value is 0.0 if the inspection has not yet been included in a DVIR record. |
| startTime * | Text | No | Timestamp when the inspection started Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z) |
| status * | inspection_status | No | The status of the inspection |
| templateId | Long | Yes | The id of the DVIR Form template used for this inspection |
| terminalId * | Long | No | The id of the Home Terminal of the User who performed the DVIR |
| userId | Long | No | The id of the user who performed the DVIR |
* this field is taken from the DVIR record that this DVIR Form is associated to. This field is only returned on the GET method if inspection has been included in the DVIR already and cannot be used in the POST and PUT method.
Read DVIR Forms
| API PATH: | /api/v3/dvirForms?is-template=true |
| METHOD: | GET |
| PARAMETERS: | is-template – Retrieves matching records for based on the boolean value provided. If true, it will return the DVIR Form templates. If false, it will the return the inspections done with the DVIR Forms (e.g. is-form=true, false by default) name – Retrieves matching records based on the name (e.g. name=Form1, all names by default) from-deleted-at – Retrieves matching records that were deleted after the specified timestamp. Setting to * will return all records. (e.g. from-deleted-at=2016-11-11T06:57:06.629Z, null by default – returns only non-deleted records) from-change-timestamp – Retrieves records modified after the timestamp supplied (e.g. from-change-timestamp=2016-11-14T04:07:03.388Z) to-change-timestamp – Retrieves records modified before the timestamp supplied (e.g. to-change-timestamp=2016-11-14T04:07:03.388Z, REQUIRES from-change-timestamp) offset – Retrieves matching records after an offset value (e.g. offset=2) limit – Retrieves a number of records per page specified by the value (e.g. limit=10) |
| SORTING: | sort=id – Sort records by their id field in ascending order (DEFAULT) sort=-id – Sort records by their id field in descending order |
| QUERY STRING EXAMPLES: | Get the DVIR Form record with the specified id: api/v3/dvirForms/54375 Get two DVIR Form records of the current Account with an offset of 1 : ?offset=1&limit=2 |
| EXAMPLE RESPONSE: |
[
{
"name": "Form A",
"description": "Test A",
"isTemplate": true,
"areas": [
{
"dvirFormId": 54375,
"index": 1,
"name": "Area A-1",
"points": [
{
"dvirAreaId": 141773,
"index": 1,
"name": "Point A1-1",
"media": [],
"id": 2844079,
"type": "triStatePoint"
}
],
"id": 141773
}
],
"accountId": 1248653,
"id": 54375,
"lastChangedDate": "2018-06-11T12:00:00.000Z"
}
]
|
Read Inspections
| API PATH: | /api/v3/dvirForms?is-template=false |
| METHOD: | GET |
| PARAMETERS: | name – Retrieves matching records based on the name (e.g. name=Form1, all names by default) user-id – Retrieves matching records for a specific Driver (e.g. driver-id=1252194, all Drivers by default) equipment-id – Retrieves matching records for a specific Equipment. Also accepts comma-separated values for multiple Equipment (e.g. equipment-id=1252194, all Equipment by default) terminal-id – Retrieves matching records for Users of a specific Terminal (e.g. terminal-id=600, all Terminals by default) filter – Retrieves matching records based on the “value” field of the inspection points (e.g. filter=defects, all by default; can only be all, defects, repaired, MINOR or MAJOR) dvir.from-end-time and dvir.to-end-time – Retrieves matching records whose DVIR endTime’s field is on or between the dvir.from-end-time and dvir.to-end-time parameters, respectively (e.g. from-end-time=2017-03-13T00:00:00.000Z&to-end-time=2017-03-14T00:00:00.000Z, all endTime by default) dvir.from-start-time and dvir.to-start-time – Retrieves matching records whose DVIR startTime’s field is on or between the dvir.from-start-time and dvir.to-start-time parameters, respectively (e.g. from-start-time=2017-03-13T00:00:00.000Z&to-start-time=2017-03-14T00:00:00.000Z, all endTime by default) from-change-timestamp – Retrieves records modified after the timestamp supplied (e.g. from-change-timestamp=2016-11-18T04:12:42.489Z) to-change-timestamp – Retrieves records modified before the timestamp supplied (e.g. to-change-timestamp=2016-11-18T04:12:42.489Z, REQUIRES from-change-timestamp) offset – Retrieves matching records after an offset value (e.g. offset=2) limit – Retrieves a number of records per page specified by the value (e.g. limit=10) |
| SORTING: | sort=id – Sort records by their id field in ascending order (DEFAULT) sort=-id – Sort records by their id field in descending order sort=driver-id – Sort records by their driverId field in ascending order sort=driver-id – Sort records by their driverId field in descending order sort=equipment-id – Sort records by their equipmentId field in ascending order sort=-equipment-id – Sort records by their equipmentId field in descending order sort=equipment-type – Sort records by the assetType field of the equipment based on their equipmentId field in ascending order sort=-equipment-type – Sort records by the assetType field of the equipment based on their equipmentId field in descending order sort=start-time – Sort records by their startTime field in ascending order sort=-start-time – Sort records by their startTime field in descending order sort=inspection-type – Sort records by their inspectionType field in ascending order sort=-inspection-type – Sort records by their inspectionType field in descending order sort=location – Sort records by their location field in ascending order sort=-location – Sort records by their location field in descending order sort=defects – Sort records by the number of defects in their points ordered by MAJOR and then MINOR severity in ascending order sort=-defects – Sort records by the number of defects in their points ordered by MAJOR and then MINOR severity in descending order sort=repairs – Sort records by the number of repairs in their points in ascending order sort=-repairs – Sort records by the number of repairs in their points in descending order |
| QUERY STRING EXAMPLES: | Get the inspection record with the specified id: api/v3/dvirForms/44863 Get two inspection records of the current Account with an offset of 1 : ?offset=1&limit=2 Get all inspection records of the current Account sorted by driver-id in ascending order: ?sort=driver-id |
| EXAMPLE RESPONSE **: |
[
{
"name": "Form A",
"isTemplate": false,
"userId": 1253185,
"equipmentId": 1326981,
"startTime": "2016-06-13T07:04:44.820Z",
"endTime": "2016-06-13T08:21:48.098Z",
"status": "CERTIFIED",
"inspectionType": "PRE_TRIP",
"inspectorType": "DRIVER",
"location": "",
"odometerKm": 0.0,
"equipmentCondition": "SATISFACTORY",
"dvirId": 22122,
"areas": [
{
"dvirFormId": 44863,
"index": 1,
"name": "Area A-1",
"points": [
{
"dvirAreaId": 118356,
"index": 1,
"name": "Point A1-1",
"value": "false",
"timestamp": "2018-06-18T04:07:41.040Z",
"severity": "MINOR",
"comment": "test comment",
"repaired": false,
"repairOrderNumber": "0",
"media": [],
"id": 2364380,
"type": "triStatePoint"
}
],
"id": 118356
}
],
"terminalId": 600,
"templateId": 54375,
"accountId": 1248697,
"id": 44863,
"lastChangedDate": "2018-06-18T04:12:42.489Z"
}
]
|
** additional fields marked with * from the table are also included in the response if inspection has been included in the DVIR already.
Create DVIR Forms
| API PATH: | /api/v3/dvirForms |
| METHOD: | POST |
| EXAMPLE REQUEST: |
[
{
"name": "Form A",
"description": "Test A",
"isTemplate": true,
"areas": [
{
"index": 1,
"name": "Area A-1",
"points": [
{
"index": 1,
"name": "Point A1-1",
"media": [],
"type": "triStatePoint",
"severity": "MINOR"
}
]
}
]
}
]
|
| EXAMPLE RESPONSE: |
[
{
"name": "Form A",
"description": "Test A",
"isTemplate": true,
"areas": [
{
"dvirFormId": 54375,
"index": 1,
"name": "Area A-1",
"points": [
{
"dvirAreaId": 141773,
"index": 1,
"name": "Point A1-1",
"media": [],
"id": 2844079,
"type": "triStatePoint",
"severity": "MINOR"
}
],
"id": 141773
}
],
"accountId": 1248653,
"id": 54375,
"lastChangedDate": "2018-06-14T04:07:03.388Z"
}
]
|
Create Inspections
| API PATH: | /api/v3/dvirForms |
| METHOD: | POST |
| PREREQUISITE: | User must have a role of ROLE_DRIVER |
| EXAMPLE REQUEST: |
[
{
"name": "Form A",
"equipmentId": 1326981,
"templateId": 54375,
"areas": [
{
"index": 1,
"name": "Area A-1",
"points": [
{
"index": 1,
"name": "Point A1-1",
"value": false,
"severity": "MINOR",
"comment": "test comment",
"repaired": false,
"timestamp": "2018-06-18T04:07:41.040Z",
"repairOrderNumber": "0",
"media": [],
"type": "triStatePoint"
}
]
}
]
}
]
|
| EXAMPLE RESPONSE: |
[
{
"name": "Form A",
"isTemplate": false,
"userId": 1253185,
"equipmentId": 1326981,
"odometerKm": 0.0,
"dvirId": 0,
"areas": [
{
"dvirFormId": 44863,
"index": 1,
"name": "Area A-1",
"points": [
{
"dvirAreaId": 118356,
"index": 1,
"name": "Point A1-1",
"value": "false",
"timestamp": "2018-06-18T04:07:41.040Z",
"severity": "MINOR",
"comment": "test comment",
"repaired": false,
"repairOrderNumber": "0",
"media": [],
"id": 2364380,
"type": "triStatePoint"
}
],
"id": 118356
}
],
"terminalId": 600,
"templateId": 54375,
"accountId": 1248697,
"id": 44863,
"lastChangedDate": "2018-06-18T04:12:42.489Z"
}
]
|
Update DVIR Forms
| API PATH: | /api/v3/dvirForms |
| METHOD: | PUT |
| EXAMPLE REQUEST: |
[
{
"name": "Form A-edit",
"description": "Test A (edited)",
"isTemplate": true,
"areas": [
{
"dvirFormId": 54375,
"index": 1,
"name": "Area A-1",
"points": [
{
"dvirAreaId": 141773,
"index": 1,
"name": "Point A1-1",
"media": [],
"id": 2844079,
"type": "triStatePoint",
"severity": "MINOR"
}
],
"id": 141773
}
],
"id": 54375
}
]
|
| EXAMPLE RESPONSE: |
[
{
"name": "Form A-edit",
"description": "Test A (edited)",
"isTemplate": true,
"areas": [
{
"dvirFormId": 54375,
"index": 1,
"name": "Area A-1",
"points": [
{
"dvirAreaId": 141773,
"index": 1,
"name": "Point A1-1",
"media": [],
"id": 2844079,
"type": "triStatePoint",
"severity": "MINOR"
}
],
"id": 141773
}
],
"accountId": 1248653,
"id": 54375,
"lastChangedDate": "2018-06-14T04:07:03.388Z"
}
]
|
Update Inspections
| API PATH: | /api/v3/dvirForms |
| METHOD: | PUT |
| PREREQUISITE: | User must have a role of FLEET_MANAGER or higher |
| EXAMPLE REQUEST: |
[
{
"name": "Form A",
"isTemplate": false,
"userId": 1253185,
"equipmentId": 1326981,
"templateId": 54375,
"odometerKm": 0.0,
"dvirId": 0,
"areas": [
{
"dvirFormId": 44863,
"index": 1,
"name": "Area A-1",
"points": [
{
"dvirAreaId": 118356,
"index": 1,
"name": "Point A1-1",
"value": "false",
"timestamp": "2018-06-18T04:07:41.040Z",
"severity": "MINOR",
"comment": "test comment",
"repaired": true,
"repairOrderNumber": "0",
"media": [],
"id": 2364380,
"type": "triStatePoint"
}
],
"id": 118356
}
],
"id": 44863
}
]
|
| EXAMPLE RESPONSE: |
[
{
"name": "Form A",
"isTemplate": false,
"userId": 1253185,
"equipmentId": 1326981,
"odometerKm": 0.0,
"dvirId": 0,
"areas": [
{
"dvirFormId": 44863,
"index": 1,
"name": "Area A-1",
"points": [
{
"dvirAreaId": 118356,
"index": 1,
"name": "Point A1-1",
"value": "false",
"timestamp": "2018-06-18T04:07:41.040Z",
"severity": "MINOR",
"comment": "test comment",
"repaired": true,
"repairOrderNumber": "0",
"media": [],
"repairedAt": "2018-07-15T00:00:00.000Z",
"id": 2364380,
"type": "triStatePoint"
}
],
"id": 118356
}
],
"terminalId": 600,
"templateId": 54375,
"accountId": 1248697,
"id": 44863,
"lastChangedDate": "2018-06-18T04:12:42.489Z"
}
]
|
Delete
| API PATH: | /api/v3/dvirForms/<id> |
| METHOD: | DELETE |
API error calls
| ERROR MESSAGE | POSSIBLE CAUSES |
| Area: <AreaName> has two or more points with duplicate names, this is not allowed | POST error because DVIR Form has inspection points with the same name within the specified area |
| Inspection points should have severity | POST or PUT error because DVIR Form templates need to a have a default severity for each DVIR Point. |
| DVIR Form with ID <id> does not exist. | PUT error because DVIR Form id does not exist. |