Introduction

Account Manager is a web tool that allows fleet managers to remotely create CoPilot settings and vehicle routing profiles and assign those settings and profiles to vehicle and driver groups within the fleet. The Fleet API supports most of Account Manager’s Configure Fleet Settings. It can be used to automate tasks including:

• Entering vehicles and drivers into Account Manager.
• Creating vehicle and driver groups.

Prerequisites

To use the Fleet API, you must be a CoPilot customer, and contact Trimble Maps to request an API key. All API calls must first be authenticated, using this key.

Use cases

Entering vehicle and drivers

The most common use of the Fleet API is to enter vehicles or drivers and to organize them in vehicle or driver groups. (Instead of entering your assets and creating groups manually in the Account Manager web tool.)

This can be done by either:

• A Trimble Maps partner/reseller who maintains accounts for their customers.
• A direct CoPilot customer/fleet account who has Account Manager access.

Any vehicles, drivers, or groups entered via the Fleet API will be visible in Account Manager, and they can be updated in the web tool or via the Fleet API.

Naming vehicle and drivers

All names and IDs (vehicle, drivers, and groups) must be unique in an account for direct CoPilot customer/fleet customers. For Trimble Maps partners/resellers who provide Account Manager accounts for customers, names and IDs must be unique across their customer base.

Up to 50 vehicles or drivers can be added to an account per API call.

Operation

The Fleet API is a RESTful API, and the base URL for all Fleet API calls is:
https://fleets.trimblemaps.com/api/assets/v1

Fleet API endpoints use the following methods:

• GET - Retrieves data from the Fleet API server.
• PUT - Updates data that is stored in the server.
• POST - Sends data to the server for processing and returns data, such as a filtered list.
• DELETE - Removes data from the server.

Read more about how to call Trimble Maps RESTful APIs.

Concepts

Fleets organize their assets in Account Manager either by vehicles or by drivers.

• Driver-based fleets assign Account Manager settings based on the driver, regardless of the vehicle or device that is using CoPilot.
• Vehicle-based fleets assign settings based on the vehicle or the device that is using CoPilot.

In most cases, the decision whether to organize settings by vehicle or by driver will be made at the time that you or one of your CoPilot customers purchase CoPilot.

Getting Started

All interactions with the Fleet API start with authentication. The process is slightly different depending on whether you are a fleet managing your own fleet account or a Trimble Maps partner/reseller managing accounts on behalf of your customers.

Authentication

For partners

Step 1: Authenticate with the API key to get a list of associated accounts.

• Call /accounts/authenticate with the provided API key to get an authentication token.
• Call /accounts with the token in the authorization header to get a list of associated accounts with corresponding AccountIds and AccountNames

Step 2: Authenticate with the API Key and an AccountId to manage a specific account.

• Call /accounts/authenticate with provided API key and AccountId to get authentication token specific to a fleet account.

For direct customers

• Call /accounts/authenticate with the provided API key to get an authentication token.

Using the API

You can call any of the Fleet API endpoints with the fleet account token in the authorization header. The endpoints are grouped in the following categories, based on the tasks they can accomplish.

• Drivers to add or edit drivers.
• Vehicles to add or edit vehicles.
• VehicleGroups to create groups of vehicles.
• DriverGroups to create groups of drivers.

Additional Links

Account Manager web tool Account Manager user guide