> ## Documentation Index
> Fetch the complete documentation index at: https://developer.plugsurfing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**](/reference/createFleet)

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:

```json theme={null}
POST /emp/v1/fleets

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

The API returns the created fleet details:

```json theme={null}
{
  "fleetId": "acme-corp-001",
  "fleetName": "Acme Corporation Fleet"
}
```

#### Error Handling

* **400 Bad Request:** Returned if `fleetId` is missing, invalid, or exceeds maximum length
* **409 Conflict:** Returned if `fleetId` already exists and the provided `fleetName` differs from the existing fleet name
* **500 Internal Server Error:** Returned for server-side errors

### Rename a Fleet

[**API Reference**](/reference/renameFleet)

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:

```json theme={null}
PUT /emp/v1/fleets/acme-corp-001/rename

{
  "newName": "Acme Industries Fleet"
}
```

The API returns the updated fleet details:

```json theme={null}
{
  "fleetId": "acme-corp-001",
  "fleetName": "Acme Industries Fleet"
}
```

#### Error Handling

* **400 Bad Request:** Returned if `newName` is missing, invalid, or exceeds maximum length
* **403 Forbidden:** Returned if the caller does not have access to the fleet organization
* **404 Not Found:** Returned if the specified `fleetId` does not exist
* **409 Conflict:** Returned if the fleet cannot be renamed to the requested `newName` (for example, if the name already exists)
* **500 Internal Server Error:** Returned for server-side errors

### Get Fleet Invitation Codes

[**API Reference**](/reference/getFleetInvitationCodes)

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:

```json theme={null}
[
  {
    "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](/docs/drive-api/charging-keys) 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](/reference/getEmpLocationById) EMP endpoint, you can include the `fleetId` parameter to retrieve pricing specific to that fleet.

See the [Geosearch guide](/docs/drive-api/geosearch) 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**](/reference/listEmpChargingKeys)

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

## Related Resources

* [EMP Mode Overview](/docs/drive-api/emp) - Learn about EMP mode and fleet-centric operations
* [Charging Keys](/docs/drive-api/charging-keys) - Manage charging keys within your fleet
* [Geosearch](/docs/drive-api/geosearch) - Retrieve fleet-specific pricing for locations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.