Customer Meta Data

The Customer Meta Data (CMD) API is a RESTful web service that enables Fleetmatics customers to integrate 3rd party back-office systems with REVEAL to keep driver, user, vehicle, and group information up to date.

The Customer Meta Data API is separated out into different services that have a variety of methods that can be accessed to create, update, and delete key objects within a REVEAL account.

This documentation will breakdown each of the services and the methods that are available: Drivers, Users, Vehicles, and Groups.

Key concepts for using the Customer Meta Data API methods:

·      Customer Meta Data API is offered as a RESTful web service

·      Standard REST verbs are applied: GET, POST, PUT, DELETE

·      Customer Meta Data API services: Drivers, Users, Vehicles, and Groups

·      Throughout this document, we will reference the unique identifier to be invoked for each of the main objects available to be created, updated, or deleted.  The unique identifiers are as follows and can be managed within the Fleetmatics REVEAL account by the same field name.

o   Driver = 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

Customer Meta Data - Driver

Endpoint

https://fim.api.eu.fleetmatics.com/cmd/v1/drivers

Operation

GET, POST, PUT, DELETE

 

GET Methods

GET Drivers

The GET Drivers methods enable integration users to retrieve Driver data by calling for all drivers within an account or a specific driver at a time. 

 

GET Drivers

The GET Vehicles method provides integration users with the ability to retrieve a list of vehicles with additional meta data.

Operation and Path

GET https://fim.api.eu.fleetmatics.com/cmd/v1/drivers 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 Drivers Sample Response

[

    {

        "Driver": {

            "CreatedDateUTC": "2014-03-24T22:49:24.667",

            "DriverNumber": null,

            "EmailAddress": "[email protected]",

            "FirstName": "Todd",

            "LastName": "Ewing",

            "EnableMobileAccess": true,

            "PhoneNumber": null

        },

        "Links": {

            "KeyFobs": {

                "Href": ""

            },

            "Self": {

                "Href": ""

            }

        }

    },

 

 

GET Driver by Driver Number

The GET Driver by Driver Number method enables the integration user to specify the vehicle to be retrieved.

Operation and Path

GET https://fim.api.eu.fleetmatics.com/cmd/v1/vehicles?=<VehicleNumber> 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 by Driver Number Sample Response

{

    "Driver": {

        "CreatedDateUTC": "2016-08-08T17:51:04.093",

        "DriverNumber": "100096",

        "EmailAddress": "[email protected]",

        "FirstName": "Chris",

        "LastName": "Abernathy",

        "EnableMobileAccess": false,

        "PhoneNumber": null

    },

    "Links": {

        "KeyFobs": {

            "Href": "http://api.eu.fleetmatics.com/CMD/v1/drivers/100096/Keys"

        },

        "Self": {

            "Href": "http://api.eu.fleetmatics.com/CMD/v1/drivers/100096"

        }

    }

 

GET Driver Methods Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

CreatedDateUTC

{

    "Driver": {

        "CreatedDateUTC": "2016-08-08T17:51:04.093",

The date the driver was created within the REVEAL account.

Driver Number

        "DriverNumber": "100096",

The Driver Number is the unique identifier that will be used to reference the driver within the API.  The Driver Number is not a mandatory field within the REVEAL account, but is required for the API.

Email Address

        "EmailAddress": "[email protected]",

 

The email address for the driver.  The driver email address is optional.  It is mandatory for utilizing driver related applications such as the Field App or LogBook.  A driver’s email address must be unique within an account.

First Name

        "FirstName": "Chris",

The first name of the driver.

Last Name

        "LastName": "Abernathy",

The last name of the driver.

Enable Mobile Access

        "EnableMobileAccess": false,

 

Boolean field for true or false.  Default is false.  True indicates the driver will have access of mobile applications. 

Phone Number

        "PhoneNumber": null

 

The phone number for the driver.

Key Fob Links

    "Links": {

        "KeyFobs": {

            "Href": "http://api.eu.fleetmatics.com/CMD/v1/drivers/100096/Keys"

        },

 

For accounts using Driver ID, the driver’s key fob(s) can be found using the key fob API link.

 

GET Key Fob by Driver Number

The GET Key Fob by Driver Number returns the key fobs assigned to the specified driver.

Operation and Path

GET https://fim.api.eu.fleetmatics.com/cmd/v1/drivers/<DriverNumber>/keys 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 Key Fob by Driver Number Sample Response

[

    "23456789"

]

 

 

GET Driver LogBook Settings by Driver Number

The GET Driver LogBook Settings by Driver Number method returns the LogBook Rule Set associated with the specified driver.   The integrated user will also be able to retrieve whether the driver is flagged as ELD compliant.  An API link will be provided so that other LogBook related methods can reference the settings returned in this call.

Operation and Path

GET https://fim.api.eu.fleetmatics.com/cmd/v1/driversettings/

logbooksettings/<DriverNumber>

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 LogBook Settings by Driver Number Sample Response

{

     “DriverLogBookSettings”:{

“FirstName”:”FirstName”,

“LastName”:”LastName”,

“DriverNumber”:”99”,

“Ruleset”:”Federal Property”,

“IsELD”:true

},

“Links”:{

          “Self”:{

              “Href”:“https://fim.api.eu.fleetmatics.com/cmd/v1/driversettings/logbooksettings/99”

       }

           }

}

 

GET Driver LogBook Settings by Driver Number Method Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Driver First Name

{

     “DriverLogBookSettings”:{

“FirstName”:”FirstName”,

The first name of the driver.

Driver Last Name

“LastName”:”LastName”,

The last name of the driver.

Driver Number

“DriverNumber”:”99”,

 

Driver Number is the unique identifier for Drivers created within REVEAL.  This is the same identifier provided in the GET request call in order to return the desired LogBook information.

If the provided Driver Number does not exist within the REVEAL account, a 404 error will be returned.

Ruleset

“Ruleset”:”Federal Property”,

Each country or state within the US has a different set of regulations dictating how long a driver can drive in a certain timeframe.  Depending on where the vehicle is located, a specific Ruleset will be associated with the driver and his/her trip.

Is ELD

“IsELD”:true

           },

Boolean true/false field indicating if the driver is currently flagged within the driver modal as ELD Compliant.

If the driver modal does not show an ELD flag or there is no flag set for the driver this should return as "false".

LogBook Settings Link

“Links”:

  “Self”:{

“Href”:“https://fim.api.eu.fleetmatics.com/cmd/v1

/driversettings/logbooksettings/99”

}

}

}

In addition to the leveraging the returned LogBook Setting fields, these values can also be found by referencing the LogBook Settings API link.

 

 

POST Methods

POST Driver

The POST Driver method enables integration users to create driver records within the REVEAL account.

 

POST Driver Sample Request Headers

Operation and Path

POST https://fim.api.eu.fleetmatics.com/cmd/v1/drivers HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Content-Type

application/json

Accept

application/json

Content-Length

This value will auto-generate based on the body of the request.

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

 

POST Driver Sample Response

{

    "DriverNumber": "99001",

    "EmailAddress": null,

    "FirstName": "Bill",

    "LastName": "Anderson",

    "EnableMobileAccess": false,

    "PhoneNumber": null

}

 

Successful calls will return a 201 code with the object details that were posted to the account.

 

 

POST Key Fob by Driver Number

The POST Key Fob by Driver Number enables integration users to assign Key Fobs to the driver record.  The Key Fob(s) will need to be entered as part of the body of the request. 

 

POST Key Fob by Driver Number Sample Request Headers

Operation and Path

POST https://fim.api.eu.fleetmatics.com/cmd/v1/drivers/<DriverNumber>/keys HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Content-Type

application/json

Accept

application/json

Content-Length

This value will auto-generate based on the body of the request.

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

 

PUT Methods

PUT Driver

The PUT Driver method enables integration users to edit existing drivers within a REVEAL account.  The Driver Number must be entered for the existing driver record in order to invoke the PUT Driver method to update the record.

The driver edits should be included within the body of the request.

 

PUT Driver Sample Request Headers

Operation and Path

PUT https://fim.api.eu.fleetmatics.com/cmd/v1/drivers/<DriverNumber> HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Content-Type

application/json

Accept

application/json

Content-Length

This value will auto-generate based on the body of the request.

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

 

PUT Driver Sample Response

PUT methods will not return an object review.  The response will be limited to a set of standard HTTP codes:

·      Successfully edited drivers will return a 200 code

·      Unfound Driver Numbers, or the unique identifier used for the call, will return a 404 error

·      Bad requests, typically due to an error in the call’s content, will return a 400 error

·      Invalid tokens or an Authorization problem will return a 401 error

·      If the service is unavailable at the time the call was made a 500 error will return

 

DELETE Methods

DELETE Driver

The DELETE Driver method is available for deleting driver records from a REVEAL account.

 

DELETE Driver Sample Request Headers

Operation and Path

DELETE https://fim.api.eu.fleetmatics.com/cmd/v1/drivers/<DriverNumber> HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Content-Type

application/json

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

 

DELETE Key Fobs by Driver Number

The DELETE Key Fobs by Driver Number enables integration users to delete the key fobs associated with a driver.

 

DELETE Key Fobs by Driver Number Sample Request Headers

Operation and Path

DELETE https://fim.api.eu.fleetmatics.com/cmd/v1/drivers/<DriverNumber>/keys HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Content-Type

application/json

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