Introduction to Driver Activity – Status Options API

The Driver Activity API for Status Options enables integration users the ability to create and manage available driver statuses within a 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.

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

 

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

 

API Summary Details

API Name

Driver Activity API: Status Options

Endpoint

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

Operation

GET and POST

 

GET Method

GET Driver Status Options

The GET Driver Status Options method will retrieve all available Driver Statuses previously created for a REVEAL account.

 

GET Driver Status Options Request Sample

Operation and Path

GET https://fim.api.eu.fleetmatics.com/da/v1/driverstatusoptions HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Accept

application/json

Authorization

 Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID  ], Bearer [Authorization 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

[

    {

        "Description": "Working Time",

        "Code": "Clock In",

        "DriverStatusType": "PunchIn",

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

    },

    {

        "Description": "None Working Time",

        "Code": "Clock Out",

        "DriverStatusType": "PunchOut",

        "CreatedDateUtc": "2016-12-21T19:32:14.983"

    }

]

 

POST Method

POST Driver Status Options

The POST Driver Status Options method enables integration users to create driver statuses within a REVEAL account.  Users cannot manage driver status options through the REVEAL UI and therefore all new driver statuses will need to be created from this API before applying it to a driver’s activity.

{

"Code": "Clock Out",

"Description": "None Working Time",

"DriverStatusType": "PunchOut"

}

 

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

·      NotSet = 0

·      None = 1

·      PunchIn = 2

·      PunchOut = 4

·      LunchStart = 8

·      LunchEnd = 16

·      BreakStart = 32

·      BreakEnd = 64

 

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/driverstatusoptions HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Accept

application/json

Authorization

 Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID  ], Bearer [Authorization Token]

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

 

POST Driver Status Option Sample Response

{

    "Description": "None Working Time",

    "Code": "Clock Out",

    "DriverStatusType": "4",

    "CreatedDateUtc": "2016-12-21T19:32:14.8774588Z"

}

 

Driver Status Options 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.

Created Date UTC

        "CreatedDateUtc": "2016-12-21T19:32:14.983"

 

The date the Driver Status Type Code was created within the REVEAL account and available for use to apply to a driver status activity.