Guides
Start typing to search…

Fleet Management

Learn how to create and manage fleet organizations using the Drive API. Fleets enable you to group charging keys and users together for easier management and organization-level operations.

Fleet management in the Drive API enables you to organize and manage groups of charging keys and users under a single fleet organization. This is particularly useful for businesses operating EV fleets, where you need to manage multiple charging keys and track usage at an organizational level.

What is a Fleet?

A fleet is an organizational unit that groups charging keys and users together. Fleets provide:

  • Centralized Management: Group multiple charging keys under a single fleet identifier.
  • Fleet-Specific Pricing: Access custom pricing configurations for your fleet.
  • Simplified Tracking: Monitor and manage charging activity across your entire fleet.

Fleet Identifier

Each fleet is identified by a unique fleetId that you provide when creating the fleet. This identifier:

  • Cannot be changed once the fleet is created – choose carefully, as you'll need to use this identifier in all future API calls
  • Must be unique across all fleets
  • Can be up to 100 characters long
  • Is used in subsequent API calls to reference the fleet
  • Should be meaningful to your organization (e.g., "acme-corp-fleet-01")

Fleet Management Endpoints

Create a Fleet

API Reference

Creates a new fleet organization in the system.

Request Parameters

  • fleetId (required): A unique identifier for the fleet (max 100 characters)
  • fleetName (optional): A human-readable name for the fleet (max 100 characters)

Example Use Case

When onboarding a new corporate customer, you would create a fleet to organize all their charging keys:

POST /emp/v1/fleets

{
  "fleetId": "acme-corp-001",
  "fleetName": "Acme Corporation Fleet"
}

The API returns the created fleet details:

{
  "fleetId": "acme-corp-001",
  "fleetName": "Acme Corporation Fleet"
}

Error Handling

  • 400 Bad Request: Returned if fleetId is missing, invalid, or exceeds maximum length
  • 500 Internal Server Error: Returned for server-side errors

Rename a Fleet

API Reference

Updates the name of an existing fleet without changing its identifier.

Request Parameters

  • fleetId (path parameter, required): The unique identifier of the fleet to rename
  • newName (body parameter, required): The new name for the fleet (max 100 characters)

Example Use Case

When a corporate customer rebrands or changes their organization name:

PUT /emp/v1/fleets/acme-corp-001/rename

{
  "newName": "Acme Industries Fleet"
}

The API returns the updated fleet details:

{
  "fleetId": "acme-corp-001",
  "fleetName": "Acme Industries Fleet"
}

Error Handling

  • 400 Bad Request: Returned if newName is missing, invalid, or exceeds maximum length
  • 404 Not Found: Returned if the specified fleetId does not exist
  • 500 Internal Server Error: Returned for server-side errors

Get Fleet Invitation Codes

API Reference

Retrieves all active invitation codes for a fleet. These codes allow users to join the fleet.

Request Parameters

  • fleetId (path parameter, required): The unique identifier of the fleet

Example Use Case

When you need to display or share invitation codes that allow users to join a specific fleet:

GET /emp/v1/fleets/acme-corp-001/invitation

The API returns an array of active invitation codes:

[
  {
    "code": "FLEET2024ABC"
  },
  {
    "code": "FLEET2024XYZ"
  }
]

Understanding Invitation Codes

Invitation codes provide an additional layer of security when drivers join a fleet. They serve as a secret code that drivers must know and provide to prove they are authorized to join your fleet organization. This is in addition to the charging key's visual number.

  • Users must provide the invitation code during registration or onboarding to join the fleet
  • This ensures that only authorized individuals who know the secret code can become part of your fleet

Error Handling

  • 403 Forbidden: Returned if the caller doesn't have access to the organization
  • 404 Not Found: Returned if the fleet doesn't exist or has no active invitation codes
  • 500 Internal Server Error: Returned for server-side errors

Working with Fleets

Associating Charging Keys with Fleets

Once a fleet is created, you can associate charging keys with it. When creating charging keys via the EMP endpoints, you can specify the fleetId to automatically assign the key to that fleet.

See the Charging Keys guide for more details on key management.

Fleet-Specific Pricing

Fleets can have custom pricing configurations. When querying location information via the Get location by id endpoint, you can include the fleetId parameter to retrieve pricing specific to that fleet.

See the Geosearch guide for more details.

Retrieving Fleet Charging Keys

You can retrieve all charging keys associated with a specific fleet using the Get Charging Keys endpoint with the fleetId filter parameter.

API Reference

GET /emp/v1/charging-keys?fleetId=acme-corp-001

Related Resources

Updated about 7 hours ago