The DVIR Forms API is used to handle queries for creation and editing DVIR forms. Fleet managers would be allowed to manage DVIR forms and query DVIR inspections. Drivers would be allowed to query DVIR forms and manage their own inspections per Equipment.
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 record |
| 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. |
| terminalId | Long | No | The Id of the terminal of the Driver of the specific DVIR Form. |
| templateId | Long | No | The Id of the template used in the DVIR Form. |
| signatureMediaId | Long | No | The id for the signature’s image. |
| 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 | No | 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/v2/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
}
],
"signatureMediaId": 16625545,
"accountId": 1248653,
"id": 54375,
"lastChangedDate": "2018-06-11T12:00:00.000Z"
}
]
|
Read Inspections
| API PATH: | /api/v2/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/v2/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": "2018-06-13T07:04:44.820Z",
"endTime": "2018-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/v2/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"
}
]
}
]
}
]
|
| 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": "2016-11-14T04:07:03.388Z"
}
]
|
Create Inspections
| API PATH: | /api/v2/dvirForms |
| METHOD: | POST |
| PREREQUISITE: | User must have a role of ROLE_DRIVER |
| EXAMPLE REQUEST: |
[
{
"name": "Form A",
"equipmentId": 1326981,
"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/v2/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"
}
],
"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"
}
],
"id": 141773
}
],
"accountId": 1248653,
"id": 54375,
"lastChangedDate": "2018-06-14T04:07:03.388Z"
}
]
|
Update Inspections
| API PATH: | /api/v2/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,
"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/v2/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 |
| DVIR Form with ID <id> does not exist. | PUT error because DVIR form id does not exist. |