Account Manager Introduction

The Account Manager is a web tool that allows you to distribute and manage the product licenses your fleet has purchased for CoPilot with ActiveTraffic. You can create lists of users (either drivers, devices or vehicles), remotely distribute software licenses to those users, and then re-assign your licenses as needed when your devices or staffing change.

The Account Manager API is a RESTful API that provides endpoints for managing licenses and licensed users. Trimble Maps partners can also use this API to set up Account Manager for their customers.

What Can You Do With The Account Manager API?

With this API, your company’s Account Manager administrator can:

• Add and remove licensed users. (Individual or in bulk. Up to 1,000 users can be added per API call.)
• Add and remove licensed products from users. (Individual or in bulk. Up to 1,000 users can be assigned licenses per API call.)

Getting Started

To use the Account Manager API, you must request access by contacting your Trimble Maps sales representative or our Sales team.

Account Manager Terminology

In the Account Manager, you may assign a license for CoPilot to a person (driver), a device that is installed directly in a truck, or a handheld device. To support this variety of uses, we provide a user identifier field called External Id.

External ID is the value that will be used as the User ID to log into CoPilot on a device, and it should uniquely identify the user (driver, device or vehicle). For example, an External ID could be a company issued device ID, driver ID, email address, phone number, device descriptor, or vehicle number—whatever works best for your fleet. It is the only required field when adding a new user in the Account Manager.

Resource URL

https://accounts-api.trimblemaps.com

Account Manager API Flow

For Fleets Managing Their Own Licenses

To create a new user and assign licenses within your account you would:

1. Authenticate your account and get an authToken, which should be passed as the Bearer token in each subsequent request. When requesting an authToken, the alias parameter is not required if you are authenticating on behalf of your own fleet in order to retrieve or update your own information. The alias parameter is used by Trimble Maps partners to authenticate and retrieve or update information on behalf of their customers. Partners can use the /company-list endpoint to retrieve the alias for each of their customers.

2. Add a user with a POST request to /users that includes an externalId and other optional fields.

3. Assign products to a single user with a POST request to /license/{productId} or assign products to a list of users with a POST request to /license/{productId}/bulk.

4. When assigning a license using either the /license/{productId} or the /license/{productId}/bulk endpoints, you can optionally stipulate an add-on constant if the license has an add-on. Add-ons are currently defined as: 1 = Weather; 2 = ITS; 3 = TripManagement

5. When retrieving the available licenses for the account using the /summary GET call, you will see an array for the addons in the products section.

Updating users and licenses

As your needs, devices or staffing change over time, you can:

1. Modify a user’s information with a PUT request to /users/{externalId} or delete a user with a DELETE request to /users/{externalId}.

2. Remove a license from a single user with a DELETE request to /license/{productId} or remove licenses from a list of users with a DELETE request to /license/{productId}/bulk.

3. Repeat Step 3 above to assign those licenses you have removed to new users.

For Trimble Maps Partners Setting Up Customer Accounts

As a partner, you can use our Account Manager APIs to create accounts for customers. You can then either delegate the day-to-day management of app licenses to an administrator assigned by the customer, or you can actively manage users, devices, and licenses for your customers.

To use the Account Manager API, you need to obtain an API key. Using that API key, you can generate an auth token by calling the /authenticate endpoint. This endpoint provides authentication for either partner-level activities (creating and managing customer accounts) or account-level activities (adding users, assigning licenses to users). For partner-level activities, only the apiKey parameter is required. For account-level activities, the auth token needs to also include the alias parameter.

To get started, you would:

Create a customer account

1. Call /authenticate to get a token by passing in the apiKey.

2. Include the resulting token in an Authorization header (Authorization:Bearer your authToken) and create an account using the /company endpoint.

Manage the newly created account

1. Take the alias from the Company API response and use it to get an Account auth token by calling the Authenticate API. This time, pass in both apiKey and the alias parameter.

2. Using this new Account auth token, you can then proceed to create users and then assign product licenses to those users. See steps above.

3. There are several other APIs you may want use to manage an account, including bulk operations that may be useful in partner integrations. Please see our full Account Manager API documentation for more details.