Customer Meta Data Ė Groups API

The customer Meta Data (CMD) Groups API is a RESTful web service that enables REVEAL customers to integrate 3rd party back-office systems to keep group hierarchy information up to date.

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

      The customer Meta Data (CMD) Groups API is offered as a RESTful web service

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

Throughout this document, we will reference the unique identifier to be invoked for each of the main objects available to be created or deleted.† The unique identifiers used within this API method set include:

o   Group ID

o   Driver Number

o   Vehicle Number

o   Employee ID

o   Place ID

Note: The current version of the Groups API does not support devices tracking Non-Powered Assets.  No information will return regarding Non-Powered Assets within any of the following API methods.

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 Ė Groups API

Endpoint

https://fim.api.us.fleetmatics.com/cmd/v1/groups

Operation

GET, POST, PUT, DELETE

 

GET Group Services

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.

 

GET All Groups

The GET All Groups method provides integration users with the ability to retrieve all groups within a fleet.† 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 Verizon Connect REVEAL account.

 

GET All Groups Request Header

Operation and Path

GET https://fim.api.us.fleetmatics/cmd/v1/groups HTTP/1.1

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 All Groups Sample Response

[

††††† {

††††† "Name": "CPTESTGROUP",

††††† "Id": "CPTG1"

†† },

††††† {

††††† "Name": "CPTESTGROUP 2",

††††† "Id": "CPTG2"

†† },

††††† {

††††† "Name": "Entire Fleet",

††††† "Id": "Entire Fleet"

†† },

 

††††† {

††††† "Name": "GNU",

††††† "Id": "GNU"

†† },

]

 

GET All Groups Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Name

† {

††††† "Name": "",

The name of the group created within the REVEAL account.

Id

††††† "Id": ""

† }

The unique identifier associated with the group created within the REVEAL account.† The Group ID† is an alphanumeric field that must be unique within the REVEAL account and will be mandatory in order to reference the group through the integration services.

 

GET Groups by Group ID

The GET Group by Group ID method provides integration users with the ability to retrieve all groups within a fleet by the 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 VerizoN Connect REVEAL account.

 

GET Groups by Group ID Request Header

Operation and Path

GET https://fim.api.us.fleetmatics/cmd/v1/groups/{groupid} HTTP/1.1

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Groups by Group ID Sample Response

† {

††††† "Name": "CPTESTGROUP",

††††† "Id": "CPTG1"

†† }

 

GET Groups by Group ID Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Name

† {

††††† "Name": "",

The name of the group created within the REVEAL account.

Id

††††† "Id": ""

† }

The unique identifier associated with the group created within the REVEAL account.† The Group ID† is an alphanumeric field that must be unique within the REVEAL account and will be mandatory in order to reference the group through the integration services.

 

GET Groups by Driver Number

The GET Groups by Driver Number method provides integration users with the ability to retrieve all groups the driver belongs to.† 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 Driver Number Request Header

Operation and Path

GET https://fim.api.us.fleetmatics/cmd/v1/groups/drivers/{drivernumber} HTTP/1.1

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Groups by Driver Number Sample Response

[

††††† {

††††† "Name": " Entire Test Fleet1Ē,

††††† "Id": ď999998Ē

†† },

 

††††† {

††††† "Name": " Entire Test Fleet2",

††††† "Id": "999999"

†† }

]

 

GET Groups by Driver Number Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Name

† {

††††† "Name": "",

The name of the group created within the REVEAL account.

Id

††††† "Id": ""

† }

The unique identifier associated with the group created within the REVEAL account.† The Group ID is an alphanumeric field that must be unique within the REVEAL account and will be mandatory in order to reference the group through the integration services.

 

 

GET Groups by Vehicle Number

The GET Groups by Vehicle Number method provides integration users with the ability to retrieve all groups the vehicle belongs to.† 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 Vehicle Number Request Header

Operation and Path

GET https://fim.api.us.fleetmatics/cmd/v1/groups/vehicles/{vehiclenumber} HTTP/1.1

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Groups by Vehicle Number Sample Response

[

††††† {

††††† "Name": " Entire Test Fleet1Ē,

††††† "Id": "999998"

†† },

††††† {

††††† "Name": " Entire Test Fleet2",

††††† "Id": "999999"

†† }

]

 

GET Groups by Vehicle Number Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Name

† {

††††† "Name": "",

The name of the group created within the REVEAL account.

Id

††††† "Id": ""

† }

The unique identifier associated with the group created within the REVEAL account.† The Group ID† is an alphanumeric field that must be unique within the REVEAL account and will be mandatory in order to reference the group through the integration services.

 

 

GET Groups by Employee ID

The GET Groups by Employee ID method provides integration users with the ability to retrieve all groups the user belongs to.† 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 Employee ID Request Header

Operation and Path

GET https://fim.api.us.fleetmatics/cmd/v1/groups/users/{employeeid} HTTP/1.1

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Groups by Employee ID Sample Response

[

††††† {

††††† "Name": "Entire Test Fleet1",

††††† "Id": "999997"

†† },

 

††††† {

††††† "Name": "Entire Test Fleet2",

††††† "Id": "999998"

†† },

 

††††† {

††††† "Name": "Entire Test Fleet3",

††††† "Id": "999999"

†† }

]

 

GET Groups by Employee ID Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Name

† {

††††† "Name": "",

The name of the group created within the REVEAL account.

Id

††††† "Id": ""

† }

The unique identifier associated with the group created within the REVEAL account.† The Group ID is an alphanumeric field that must be unique within the REVEAL account and will be mandatory in order to reference the group through the integration services.

 

POST to Group ID

The integrated user will be able to utilize one of the following methods in order to add information to a specific Group ID.

 

POST Drivers to Group ID

The POST Drivers by Group ID method provides integration users with the ability to add drivers to a specific Group ID.† Requests will require the Driver number in the body and the Group ID in the path.† Multiple drivers can be added to each Group ID provided as groups can contain multiple drivers within REVEAL.

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.

 

POST Drivers to Group ID Request Body

Within the body of the request, the integrated user will need to supply the Driver Number in order to add the driver to the provided Group ID.† The format of the body should be as follows:

{

† "DriverNumber": " 6543-10"

}

 

POST Drivers to Group ID Request Header

Operation and Path

POST https://fim.api.us.fleetmatics/cmd/v1/groups/{groupid}/drivers

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Drivers to Group ID Response Field Breakdown

 

Field

JSON Formatted Sample

Field Notes and Default Values

Driver Number

{

† "DriverNumber": " 6543-10"

}

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.

 

POST Drivers to Group ID Sample Response

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

      Successfully edited vehicles will return a 200 code

      Unfound Vehicle 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

 

POST Users to Group ID

The POST Users by Group ID method provides integration users with the ability to add users to a specific Group ID.† Requests will require the Employee ID in the body and the Group ID in the path.† Multiple users can be added to each Group ID provided as groups can contain multiple users within REVEAL.

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

When a user is assigned to a group this will not remove a user 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.

 

POST Users to Group ID Request Body

Within the body of the request, the integrated user will need to supply the Employee ID in order to add the user to the provided Group ID.† The format of the body should be as follows:

{

† "EmployeeId": 324234346

}

 

POST Users to Group ID Request Header

Operation and Path

POST https://fim.api.us.fleetmatics/cmd/v1/groups/{groupid}/users

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Users to Group ID Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Employee ID

{

† "EmployeeId": 324234346

}

Employee ID is the unique identifier for the user within REVEAL.† The Employee ID is not mandatory within the REVEAL account, but is required for the API.

 

POST Users to Group ID Sample Response

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

      Successfully edited vehicles will return a 200 code

      Unfound Vehicle 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

 

POST Vehicles to Group ID

The POST Vehicles by Group ID method provides integration users with the ability to add vehicles to a specific Group ID.† Requests will require the Vehicle Number in the body and the Group ID in the path.† Multiple vehicles can be added to each Group ID provided as groups can contain multiple vehicles within REVEAL.

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.

 

POST Vehicles to Group ID Request Body

Within the body of the request, the integrated user will need to supply the Vehicle Number in order to add the vehicle to the provided Group ID.† The format of the body should be as follows:

{

† "VehicleNumber": "77771-1"

}

 

POST Vehicles to Group ID Request Header

 

 

Operation and Path

POST https://fim.api.us.fleetmatics/cmd/v1/groups/{groupid}/vehicles

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Vehicles to Group ID Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Vehicle Number

{

† "VehicleNumber": "77771-1"

}

The Vehicle Number is the unique identifier within the API.† The Vehicle Number is not a mandatory field within the REVEAL account, but is required for the API.

 

POST Vehicles to Group ID Sample Request

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

      Successfully edited vehicles will return a 200 code

      Unfound Vehicle 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

 

POST Geofences to Group ID

The POST Geofences Vehicles by Group ID method provides integration users with the ability to add geofences to a specific Group ID.† Requests will require the Place ID in the body and the Group ID in the path.† Multiple geofences can be added to each Group ID provided as groups can contain multiple vehicles within REVEAL.

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.

 

POST Geofences to Group ID Request Body

Within the body of the request, the integrated user will need to supply the Place ID in order to add the geofence to the provided Group ID.† The format of the body should be as follows:

{

† "PlaceId": "WCB-Circle-151112-1"

}

 

 

POST Geofences to Group ID Request Header

Operation and Path

POST https://fim.api.us.fleetmatics/cmd/v1/groups/{groupid}/geofences

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Geofences to Group ID Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Place ID

{

† "PlaceId": "WCB-Circle-151112-1"

}

Place ID is a unique value within a REVEAL account that is used to identify a Geofence.† To use the Geospatial API the Place ID is a mandatory field.† The Place ID can be NULL for a returned Geofence.

 

POST Geofences to Group ID Sample Response

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

      Successfully edited vehicles will return a 200 code

      Unfound Vehicle 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 from Group ID

The integrated user will be able to remove information from a specified group by providing a Group ID.

 

DELETE Drivers from Group ID

The DELETE Driver by Group ID method provides integration users with the ability to remove drivers from a specific Group ID.† Requests will require the Driver Number and the Group ID in the path.† Multiple drivers can be removed to from each Group ID provided as groups can contain multiple drivers within REVEAL.

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.

 

Operation and Path

DELETE https://fim.api.us.fleetmatics/cmd/v1/groups/{groupid}/drivers/

{drivernumber}

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Drivers from Group ID Sample Response

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

      Successfully edited vehicles will return a 200 code

      Unfound Vehicle 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 Users from Group ID

The DELETE User by Group ID method provides integration users with the ability to remove users from a specific Group ID.† Requests will require the Employee ID and the Group ID in the path.† Multiple users can be removed to from each Group ID provided as groups can contain multiple users within REVEAL.

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.

Operation and Path

DELETE https://fim.api.us.fleetmatics/cmd/v1/groups/{groupid}/users/

{employeeid}

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Users from Group ID Sample Response

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

      Successfully edited vehicles will return a 200 code

      Unfound Vehicle 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 Vehicles from Group ID

The DELETE vehicles by Group ID method provides integration users with the ability to remove vehicles from a specific Group ID.† Requests will require the Vehicle Number and the Group ID in the path.† Multiple vehicles can be removed to from each Group ID provided as groups can contain multiple vehicles within REVEAL.

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.

 

Operation and Path

DELETE https://fim.api.us.fleetmatics/cmd/v1/groups/{groupid}/vehicles/

{vehiclenumber}

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Vehicles from Group ID Sample Response

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

      Successfully edited vehicles will return a 200 code

      Unfound Vehicle 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 Geofences from Group ID

The DELETE Geofences by Group ID method provides integration users with the ability to remove geofences from a specific Group ID.† Requests will require the Place ID and the Group ID in the path.† Multiple geofences can be removed to from each Group ID provided as groups can contain multiple geofences within REVEAL.

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.

 

Operation and Path

DELETE https://fim.api.us.fleetmatics/cmd/v1/groups/{groupid}/geofences/

{placeid}

HOST

https://fim.api.us.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<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 Geofences from Group ID Sample Response

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

      Successfully edited vehicles will return a 200 code

      Unfound Vehicle 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