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   Drivers = Driver Number

o   Users = Employee ID

o   Vehicles = Vehicle Number

o   Groups = Group ID

o   Geofences = Place ID

Groups

The Customer Meta Data API allows for groups to be updated using the Group Service methods.  The Group Service enables integrated users to/from assign or remove drivers, vehicle, or users to specific groups.

Group information will be invoked using the Group ID as the unique identifier.

GET Methods

·        GET All Groups

·        GET Groups by Driver Number

·        GET Groups by Vehicle Number

·        GET Groups by Employee ID

·        GET Groups by Group ID

·        GET Drivers by Group ID

·        GET Users by Group ID

·        GET Vehicles by Group ID

GET All Groups

The integrated user will be able to return group information within REVEAL by using this GET method.  This will assist the integrated user to understand the current group structure within the Fleetmatics REVEAL account in order to properly associate drivers, users, and vehicles to those groups.

The following group information will be returned when using this method:

·        Group Name

·        Group ID – this is an alphanumeric field that must be unique within the Fleetmatics REVEAL account and will be mandatory in order to reference the group through the integration services

GET Groups by Driver Number

The integrated user will be able to return group information that a driver is currently assigned to within Fleetmatics REVEAL by providing a valid Driver Number to reference.  Results will include Group Name and Group ID.  Multiple groups can be returned for each Driver Number provided as drivers can belong to multiple groups within REVEAL.

GET Groups by Vehicle Number

The integrated user will be able to return group information that a vehicle is currently assigned to within Fleetmatics REVEAL by providing a valid Vehicle Number to reference.  Results will include Group Name and Group ID.  Multiple groups can be returned for each Vehicle Number provided as vehicles can belong to multiple groups within REVEAL.

GET Groups by Employee ID

The integrated user will be able to return group information that a user is currently assigned to within Fleetmatics REVEAL by providing a valid Employee ID to reference.  Results will include Group Name and Group ID.  Multiple groups can be returned for each Employee ID provided as users can belong to multiple groups within REVEAL.

GET Groups by Group ID

The integrated user will be able to verify the Group Name that corresponds with a Group ID to ensure proper placement of drivers, vehicles, and users within the Fleetmatics REVEAL account.

PUT Methods

·        PUT Drivers to Group ID

·        PUT Users to Group ID

·        PUT Vehicles to Group ID

·        PUT Geofences to Group ID

PUT Drivers to Group ID

The integrated user will be able to update a driver to specify what group he/she should be assigned to.  The integration user will need to specify the driver by Driver Number to be added to the Group ID provided.

If the Driver Number or Group ID are not valid within the account an ERROR will be returned.

When a driver is assigned to a group this will not remove a driver from any of the previously assigned groups.  Drivers can belong to multiple groups within REVEAL.  If the driver is assigned to a parent group, the driver will also be associated with any subgroups of that parent group.

PUT Users to Group ID

The integrated user will be able to update a user to specify what group he/she should be assigned to.  The integration user will need to specify the user by Employee ID to be added to the Group ID provided.

If the Employee ID or Group ID are not valid within the account an ERROR will be returned.

When a driver is assigned to a group this will not remove a driver from any of the previously assigned groups.  Users can belong to multiple groups within REVEAL.  If the user is assigned to a parent group, the user will also be associated with any subgroups of that parent group.

PUT Vehicles to Group ID

The integrated user will be able to update a vehicle to specify what group it should be assigned to.  The integration user will need to specify the vehicle by Vehicle Number to be added to the Group ID provided.

If the Vehicle Number or Group ID are not valid within the account an ERROR will be returned.

When a vehicle is assigned to a group this will not remove a vehicle from any of the previously assigned groups.  Vehicles can belong to multiple groups within REVEAL.  If the vehicle is assigned to a parent group, the vehicle will also be associated with any subgroups of that parent group.

PUT Geofences to Group ID

The integrated user will be able to update a Geofence to specify what group it should be assigned to.  The integration user will need to specify the Geofence by the Place ID to be added to the Group ID provided.

If the Place ID or Group ID are not valid within the account an ERROR will be returned.

Geofences can be assigned to multiple groups.  Adding a Geofence to a group will not remove the Geofence from another group.

DELETE Methods

·        DELETE Drivers from Group ID

·        DELETE Users from Group ID

·        DELETE Vehicles from Group ID

·        DELETE Geofences from Group ID

DELETE Drivers from Group ID

The integrated user will be able to remove a driver from a specified group.  The integration user will need to specify the driver by Driver Number to be removed from the Group ID provided.

If the Driver Number or Group ID are not valid within the account an ERROR will be returned.

Note: if the driver is removed from all group associations, it will be placed within the Ungrouped Group within the account.  Invoking this method does NOT delete the driver record from the REVEAL account.

DELETE Users from Group ID

The integrated user will be able to remove a user from a specified group.  The integration user will need to specify the user by Employee ID to be removed from the Group ID provided.

If the Employee ID or Group ID are not valid within the account an ERROR will be returned.

Note: if the user is removed from all group associations, it will be placed within the Ungrouped Group within the account.  Invoking this method does NOT delete the user record from the REVEAL account.

Remove Vehicle from Group ID

The integrated user will be able to remove a vehicle from a specified group.  The integration user will need to specify the vehicle by Vehicle Number to be removed from the Group ID provided.

If the Vehicle Number or Group ID are not valid within the account an ERROR will be returned.

Note: if the vehicle is removed from all group associations, it will be placed within the Ungrouped Group within the account.  Invoking this method does NOT delete the vehicle record from the REVEAL account.

Remove Geofence from Group ID

The integrated user will be able to remove a Geofence from a specified group.  The integration user will need to specify the Geofence by Place ID to be removed from the Group ID provided.

If the Place ID or Group ID are not valid within the account an ERROR will be returned.

Note: if the Geofence is removed from all group associations, it will be placed within 0 Groups.  When Groups Selected is 0 the Geofence will be available for review to any users with access to view Geofences within the product.  Invoking this method does NOT delete the Geofence record from the REVEAL account.