User REST API

User REST API is a RESTful web service that enables Verizon Connect customers to integrate 3rd party back-office systems with REVEAL to keep driver, user, vehicle, and group information up to date.

The User 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 User API User methods:

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

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

·       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 REVEAL account by the same field name.

o   Drivers = Driver Number

o   Users = Employee ID

Note: To return information on Non-powered assets please call for the methods specified in Non-Powered Assets API .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 - Users

Endpoint

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

Operation

GET, POST, PUT

 

GET Methods

GET Users

The GET Users methods enable integration users to retrieve User data by calling for all users within an account or a specific user at a time.

 

GET Users

The GET User method provides integration users with the ability to retrieve a list of users with additional meta data.  Only ACTIVE users within a REVEAL account will be returned – no deactivated or deleted users will return in the query.

Operation and Path

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

HOST

fim.api.us.fleetmatics.com

Accept

application/json

Authorization

 Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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 Users Sample Response

[

    {

        "user": {

            "FirstName": "Kevin",

            "LastName": "Abarra",

            "EmailAddress": "[email protected]",

            "EmployeeId": null,

            "IsAdministrator": false,

            "IsRegionalAdministrator": false,

            "Role": "Routist/LB/WO",

            "IsDriver": true,

            "UserId": 1

        },

        "_links": null

    },

]

 

 

GET User by User ID

The GET User by User ID method enables the integration user to specify the user to be retrieved. Only ACTIVE users within a REVEAL account will be returned – no deactivated or deleted users will return in the query.

Operation and Path

GET https://fim.api.us.fleetmatics.com/cmd/v1/users?userId=<UserId> HTTP/1.1

HOST

fim.api.us.fleetmatics.com

Accept

application/json

Authorization

 Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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 User by User ID Sample Response

{

    "user": {

        "FirstName": "Dan",

        "LastName": "Bowyer",

        "EmailAddress": "[email protected]",

        "EmployeeId": 982736342,

        "MobileNumber": null,

        "IsAdministrator": false,

        "IsRegionalAdministrator": true,

        "Role": null,

        "TimeZone": "Eastern Standard Time",

        "Region": "USA",

        "Language": "en-US",

        "IsDriver": false,

        "DriverNumber": null,

        "UserId": 1

    },

    "_links": {

        "self": {

            "href": "http://api.us.fleetmatics.com/CMD/v1/users/982736342"

        },

        "groups": {

            "href": "http://api.us.fleetmatics.com/CMD/v1/groups/users/982736342"

        }

    }

}

 

GET User by Employee ID

The GET User by Employee ID method enables the integration user to specify the user to be retrieved. Only ACTIVE users within a REVEAL account will be returned – no deactivated or deleted users will return in the query.

Operation and Path

GET https://fim.api.us.fleetmatics.com/cmd/v1/users/982736342 HTTP/1.1

HOST

fim.api.us.fleetmatics.com

Accept

application/json

Authorization

 Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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 User by Employee ID Sample Response

{

    "user": {

        "FirstName": "Dan",

        "LastName": "Bowyer",

        "EmailAddress": "[email protected]",

        "EmployeeId": 982736342,

        "MobileNumber": null,

        "IsAdministrator": false,

        "IsRegionalAdministrator": true,

        "Role": null,

        "TimeZone": "Eastern Standard Time",

        "Region": "USA",

        "Language": "en-US",

        "IsDriver": false,

        "DriverNumber": null,

        "UserId": 1

    },

    "_links": {

        "self": {

            "href": "http://api.us.fleetmatics.com/CMD/v1/users/982736342"

        },

        "groups": {

            "href": "http://api.us.fleetmatics.com/CMD/v1/groups/users/982736342"

        }

    }

}

 

GET User Methods Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

First Name

{

    "user": {

        "FirstName": "Dan",

The first name of the user.

Last Name

        "LastName": "Bowyer",

The last name of the user.

Email Address

        "EmailAddress": "[email protected]",

The email address for the user. The email address is also the REVEAL username login and is mandatory when creating a user record.

Employee ID

        "EmployeeId": 982736342,

 

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

Mobile Number

        "MobileNumber": null,

The phone number for the user.

Is Administrator

      "IsAdministrator": false,

Boolean field for true or false.  Default is false.  True indicates that the user is an Administrator for the referenced REVEAL account.  Administrator is the highest level role within a REVEAL account.

Is Regional Administrator

        "IsRegionalAdministrator": true,

Boolean field for true or false.  Default is false.  This field can only be set to true if the corresponding REVEAL account is enabled Regional Administration permission.  If you do not know if the account you are working with has Regional Administrator privilege contact Verizon Connect Customer Care or leave the default as false.

Role

        "Role": null,

Role can be NULL if the user is an Administrator or a Regional Admin, as shown in this example.  If the user is not an administrator, then the name of the role applied to the user will be returned.  Roles are created within the REVEAL account’s Admin section.

TimeZone

        "TimeZone": "Eastern Standard Time",

The time zone selection that the user has configured for how time should be represented when the specified user is logged into REVEAL.  If NULL the user’s time zone will be set to the Account Preference’s selection.  Time Zone requests and responses format follow ISO time zone abbreviations.

Region

        "Region": "USA",

The Region selection for the user.  Region requests and responses format follow ISO alpha 3 country codes for the list of countries currently supported by REVEAL.

Language

        "Language": "en-US",

The Language selection for the user.  Language requests and responses format follow IETF language tags for the list of languages currently supported by REVEAL.

Is Driver

        "IsDriver": false,

Boolean field for true or false.  Default is false.  When creating or editing a user, the user can be specified to also appear as a Driver within the REVEAL account.  If the API user requests for a User to also be a Driver, a unique Driver Number must also be provided.

Driver Number

        "DriverNumber": null

   

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.

User Id

        "UserId": 1

   

This is an integer that serves as a primary key, uniquely identifying each record in the table.

Links

    "_links": {

        "self": {

            "href": "http://api.us.fleetmatics.com/CMD/v1/users/982736342"

        },

        "groups": {

            "href": "http://api.us.fleetmatics.com/CMD/v1/groups/users/982736342"

        }

    }

}

The links provided will enable the integration user to gather additional meta data for a User record.  Additionally, the “groups” link will provide details on which groups the User record belongs to within the REVEAL account.

 

 

POST Methods

POST User

The POST User method enables integration users to create user records within the REVEAL account.

Within the content body of the request the following fields should be provided:

{

           "FirstName": "Lonny",

           "LastName": "Arking",

           "EmailAddress": "[email protected]",

           "EmployeeId": "777099",

           "MobileNumber": null,

           "IsAdministrator": "true",

           "IsRegionalAdministrator": false,

           "Role": "Demo",

           "TimeZone": null,

           "Region": null,

           "Language": null,

           "IsDriver": false,

           "DriverNumber": null

         }

 

 

Operation and Path

POST https://fim.api.us.fleetmatics.com/cmd/v1/users HTTP/1.1

HOST

fim.api.us.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 atmosphere_app_id=fleetmatics-p-us-[ 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 User Sample Response

When a POST User method has been successfully called with a 201 return the user object will be provided within the response:

{

    "FirstName": "Lonny",

    "LastName": "Arking",

    "EmailAddress": "[email protected]",

    "EmployeeId": 777099,

    "MobileNumber": null,

    "IsAdministrator": true,

    "IsRegionalAdministrator": false,

    "Role": "Demo",

    "TimeZone": null,

    "Region": null,

    "Language": null,

    "IsDriver": false,

    "DriverNumber": null

}

 

PUT Methods

PUT User

The PUT User method enables integration users to edit existing user records within the REVEAL account.

Within the content body of the request the following fields should be provided:

{

    "FirstName": "Lonny",

    "LastName": "Arking",

    "EmailAddress": "[email protected]",

    "EmployeeId": 777099,

    "MobileNumber": null,

    "IsAdministrator": false,

    "IsRegionalAdministrator": false,

    "Role": "Demo",

    "TimeZone": null,

    "Region": null,

    "Language": null,

    "IsDriver": false,

    "DriverNumber": null

}

 

Operation and Path

PUT https://fim.api.us.fleetmatics.com/cmd/v1/users/777099 HTTP/1.1

HOST

fim.api.us.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 atmosphere_app_id=fleetmatics-p-us-[ 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.

 

 

PUT Deactivated Status by Employee ID

The PUT Deactivated Status by Employee ID method enables integration users to flag users as deactivated within a REVEAL account.  REVEAL allows for both deactivated and deleted object row states however only the deactivation option is made available through the API.

Within the content body of the request the following fields should be provided:

{

               "Deactivate": true

             }

 

Operation and Path

PUT https://fim.api.us.fleetmatics.com/cmd/v1/users/777099 HTTP/1.1

HOST

fim.api.us.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 atmosphere_app_id=fleetmatics-p-us-[ 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.

 

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