RESTful APIs

Introduction

Contents

FleetPortal 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 FleetPortal’s features. It can be used to automate tasks including:

  • Entering vehicles and drivers into FleetPortal.
  • Creating vehicle and driver groups.

Prerequisites

To use the Fleet API, you must be a CoPilot customer licensed for FleetPortal, 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 FleetPortal web tool.)

This can be done by either:

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

Any vehicles, drivers, or groups entered via the Fleet API will be visible in FleetPortal, 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 FleetPortal 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 FleetPortal either by vehicles or by drivers.

  • Driver-based fleets assign FleetPortal 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 and sign up for FleetPortal.

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 FleetPortal account or a Trimble Maps partner/reseller managing FleetPortal 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.

FleetPortal web tool FleetPortal web tool user guide

Last updated July 6, 2023.
Contents