Introduction to Driver Activity Ė Driver Status API

The Driver Activity API for Driver Status enables integration users the ability to assign different statuses to drivers within their REVEAL account.

The standard practice for Driver Statuses would be to manage and track clock in/out data for your drivers or technicians and compare that data to the vehicleís location information.

In order to see clock in/out data within your REVEAL account, the Timecard feature will need to be enabled.If you plan to use the Driver Activity Ė Status Options and Status APIs, please contact Verizon Connect Customer Support to have your account enabled with the Timecard feature to see clock in/out data appear on your Daily report.

Note: Driver Statuses are different than Work Order Statuses.A Driver Status should be managed based on the driverís actual daily activity and not in association with the status of a job during his/her day.

Important concepts to understand prior to utilizing any of the available integration methods:

      Driver Activity API is offered as a RESTful web service

      Standard REST verbs are applied: GET, POST

      The Driver Activity API is broken out into three components: Driver Assignments, Driver Status Options, and Driver Status

      Throughout this document, the following unique identifiers will be referenced:

o   Driver Number

Note: The returned response will be restricted to the Reveal account's data plan. If the information being queried is outside of the data plan, a "400 Bad Request error "response will be returned.

For more details on your account's data plan please reach out to Verizon Connect Customer Support

 

API Summary Details

API Name

Driver Activity API: Driver Status

Endpoint

https://fim.api.eu.fleetmatics.com/da/v1/driverstatuses

Operation

GET and POST

 

GET Method

GET Driver Status by Driver Number

The GET Driver Status by Driver Number enables integration users the ability to retrieve a specified driverís current status.

 

GET Driver Status Options Request Sample

Operation and Path

GET https://fim.api.eu.fleetmatics.com/da/v1/driverstatuses/<DriverNumber>?driverNumber=<DriverNumber> HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_<Fleetmatics Integration Manager App ID>, Bearer <token>

Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

GET Driver Status Options Response Sample

{

††† "Code": "Clock In",

††† "Description": "Working Time",

††† "DriverNumber": "710",

††† "DriverStatusType": "PunchIn",

††† "StatusChangeDateUtc": "2016-12-22T09:29:36.513"

}

 

POST Method

POST Driver Status

The POST Driver Status method enables the integration user the ability to manage a driverís statuses throughout the day.This method can enable REVEAL users the option to compare a driverís statuses against the vehicle activity.If the REVEAL account is also using work order integration, driver statuses can be compared against the work orders and work order statuses to provide additional context for time stated as working time against unproductive time.

The Driver Status API cannot be used to apply statuses to a particular driver until the Driver Status Option API has first been used to configure the applicable driver statuses available within an account.

{

"Code": "Clock In",

"DriverNumber": "100096",

"StatusChangeDateUtc": "2016-12-21T19:29:36.513"

}

 

 

At this time, only PunchIn and PunchOut driver status information data will display within the REVEAL designated reports to show punch in and out data.Integration users can send additional driver statuses available within REVEAL, but only Punch In and Out statuses will be shown within the UI.

 

POST Driver Status Options Request Sample

Operation and Path

POST https://fim.api.eu.fleetmatics.com/da/v1/driverstatuses HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_<Fleetmatics Integration Manager App ID>, Bearer <token>

Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

 

Driver Status Field Mapping

Field

JSON Formatted Sample

Field Notes and Default Values

Code

†††††††† "Code": "Clock Out",

 

The Driver Status Type Code string value that will be displayed as reference within REVEAL where available.

Description

††††††† "Description": "Working Time",

 

The Description is a string field that is provided by the integration user to provide context for the Driver Status Type Code to be referenced.

Driver Status Type

††††††††† "DriverStatusType": "PunchOut"

 

The content of the request must map to the following DriverStatusType options available:

       NotSet

       None

       PunchIn

       PunchOut

       LunchStart

       LunchEnd

       BreakStart

       BreakEnd

At this time, only PunchIn and PunchOut driver status information data will display within the REVEAL designated reports to show punch in and out data.Integration users can send additional driver statuses available within REVEAL, but only Punch In and Out statuses will be shown within the UI.

When a POST is made successfully, the enumerator value that the Driver Status Type is mapped to will display as shown in the above samples.

 

Status Change Date UTC

†††††††††† "StatusChangeDateUtc": "2016-12-21T19:29:36.513"

 

The date and time the status was applied to the referenced Driver Number.