Getting Started

The Fleet Service API is organized around REST, uses standard verbs and returns HTTP status codes and JSON-encoded responses. Every call to a Fleet Service API requires authentication with a bearer token.

Step 1: Account Setup Work with your WEX account team to onboard you to the platform. WEX will create your account, provision a testing environment and provide you with a client_id and client_secret.

Be sure to keep your credentials secure, and do not share them in publicly accessible areas.

Step 2: Authentication The Fleet Service API uses OAuth 2 and requires a bearer access token, specifically, a JSON WEB Token (JWT), in the header of every request.

To get a bearer access token for the Fleet Service API, you must successfully make a POST request to our OAuth API to exchange your client_id and secret for a token.

A cURL request demonstrating an Authorization request, exchanging your client_id/secret_id for an access token in the “XC” testing environment.

curl --location --request POST 
'https://wmd.xc.wexonline.com/oauth-service/uaa/oauth/token' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--header 'Accept-Encoding: gzip,deflate,br' \ 
--data 'grant_type=client_credentials&client_secret=1234&client_id=some-client-id'

A successful response from this request will have an access_token field populated as part of the JSON response. Use this value in your future calls to the Fleet Service API. All API requests must be made over HTTPS. API requests without authentication will fail.

Generaral Authentication Notes:

• Do not add Scope to your Authorization request.

• The JWT has a token expiration time, after which the Fleet Service API will respond with a 401 server code.

• A JWT will invalidate if the same client credentials are used to create another token.

• You should resuse your JWT until expiration of invalidation, regenerating your token after receiving a 401 server code.

Step 3: Making API Calls Now that you have a bearer token, you’re ready to start making API requests. The Fleet Services API allows you to make a variety of API calls depending upon your desired task. To begin exploring using the API, let’s look at two scenarios and multiple examples to illustrate making API calls. Check out the Recipes section for more use case examples.

The Fleet Services API allows you to make a variety of API calls depending upon your desired task. This guide uses two scenarios and multiple examples to illustrate making API calls.

Scenario 1: I am a Fleet Manager. I want to update my driver’s cell phone number. How do I update the phone number?

Example A:

Assumption: The user has a driverId and the new phone number.

Step 1. Provide the driverId and the new phone number as body parameters to the PATCH/drivers/{driverId} endpoint.

Example B:

Assumption: The user does not know the driverId but knows the phone number and accountId [1-1JA826S].

Step 1. Use the GET/drivers endpoint by providing the following query parameter:

query_string:account_id“1-1JA826S” AND phone_number : “2125551212”.

Step 2. Get the driver_id in the response from Step 1.

Step 3. Provide the driver_id and the new phone number as body parameters to the PATCH/driver/{driverId} endpoint.

Example C:

Assumption: The user does not know the accountId and driverId but knows the phone number.

Step 1. Use the GET/accounts endpoint to retrieve a list of all the accounts to which the user has access.

Step 2. Get an account_id on the response from Step 1.

Step 3. Use the GET/drivers endpoint by providing the following query parameter.

query_string:account_id.keyword:<accountId> from step #2.

Step 4. Get the driver_id in the response from Step 3.

Step 5. Provide a driver_id and the new phone number as body parameters to the PATCH/drivers/{driverId} endpoint.

Scenario 2: I am a Fleet Manager. I want to search for a vehicle using a vehicle identification number (VIN). How do I find the vehicle?

Example A:

Assumption: The user does not know the account_id but knows the VIN number.

Step 1. Use the GET/accounts endpoint to retrieve a list of all accounts to which the user has access.

Step 2. Get an account_id on the response from Step 1.

Step 3. Use the GET/vehicles endpoint by providing the following query parameter:

query_string:account_id.keyword:<accountId> from step #2> AND vin:JMVINAUTO12495615