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

# Fleet management

> Provision a fleet's drivers, vehicles, and accounts, then track their charging through the API.

By the end of this playbook you'll know how to set a fleet up on Spirii from your own system — its accounts, drivers, and vehicles — and how to pull the charging data back to power route planning, cost control, and reporting.

## Before you start

This playbook is for fleet management and telematics platforms integrating with Spirii. You'll need an [API key](/developers/authentication) — created by an operator in Connect, it grants access to every endpoint you'll use here — and a working understanding of [tokens](/components/access/tokens), which are how drivers and vehicles authenticate to charge.

## How the pieces fit

Two objects carry a fleet integration, and it helps to hold them in mind before you start:

* A **customer** is an account you bill — a sub-fleet, department, or cost centre.
* A **token** is how a driver (an app or RFID) or a vehicle (Autocharge) authenticates to charge. Registering a token grants it access to charge; each token is linked to the customer that should be billed.

Once drivers and vehicles start charging, each session becomes a transaction and then a CDR, carrying the token and customer, so you can attribute every kWh back to a driver, vehicle, or sub-fleet.

If a depot is a public location and you want to keep it to your fleet, a token group can restrict charging there to a chosen set of tokens — but for a private depot the token alone is enough, so it isn't part of the setup below.

## Set up the fleet

<Steps>
  <Step title="Model sub-fleets as customers">
    Create a customer for each account you bill separately. Set its `type` (usually `Business`), the parent account via `ownerId`, and an `externalId` that maps it to the account in your own system.

    ```bash theme={null}
    curl -X POST https://api.spirii.com/v2/customers \
      -H "Authorization: Bearer <SPIRII_API_KEY>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Acme Logistics — North depot",
        "type": "Business",
        "ownerId": 234,
        "externalId": "CU-12345",
        "country": "DE",
        "contactDetails": { "name": "Fleet Admin", "email": "fleet@example.com" }
      }'
    ```

    See [Create a customer](https://docs.spirii.com/api-reference/customer-v2/create-a-new-customer) for the billing and financial fields to include if you use Spirii's financial services.
  </Step>

  <Step title="Register drivers' and vehicles' tokens">
    A fleet usually already has the means to charge — RFID charge cards, or fuel cards with an RFID chip that can be repurposed for charging. Creating a token in the platform registers that credential so Spirii recognises it and authenticates charging against it. You'll typically:

    * **register RFID tokens** the fleet already holds, by their chip UID,
    * **create virtual tokens** for drivers authenticating through an app,
    * **register vehicle (Autocharge) tokens** by a vehicle's MAC address or VIN.

    Link each token to the customer that should be billed with `customerId`.

    ```bash theme={null}
    curl -X POST https://api.spirii.com/v2/tokens \
      -H "Authorization: Bearer <SPIRII_API_KEY>" \
      -H "Content-Type: application/json" \
      -d '{
        "customerId": 123,
        "identifier": { "type": "rfid", "uid": "A7E942F1C8D036B5A429", "label": "VAN-07" }
      }'
    ```

    See [Create a token](https://docs.spirii.com/api-reference/tokens/create-a-new-token) and the [Tokens](/components/access/tokens) component for the three token types and their fields.
  </Step>
</Steps>

## Verify

<Check>
  Have a provisioned token start a charge at the depot. The session appears in [Transactions](https://docs.spirii.com/api-reference/transactions-v2/get-a-list-of-transactions), and once it ends a CDR is generated carrying that token and its customer — confirming both access and billing attribution are set up correctly.
</Check>

## Track charging

Once the fleet is charging, the API gives you both a live view and a settled record. The generic retrieval mechanics — paging, incremental sync, and the rate and record limits — are covered in the [Reporting and dashboards](/developers/reporting-and-dashboards) playbook; below is what matters for a fleet, starting with the live view, which is where this integration earns its keep.

### Live sessions and state of charge

The live session feed is the most valuable one for a fleet. [Transactions](https://docs.spirii.com/api-reference/transactions-v2/get-a-list-of-transactions) lists sessions in progress and recently finished, so you can see which vehicles are charging right now, how much they've drawn so far, and, on DC chargers, the vehicle's reported state of charge, which tells you when it will be ready to leave. Filter to a token to follow a single driver or vehicle in real time.

Feed this into dispatch, route planning, and live operations dashboards: a vehicle's charge level and expected ready time are exactly what a fleet system needs to plan the next leg.

### Depot status

Poll [Locations](https://docs.spirii.com/api-reference/locations-v2/fetches-a-list-of-locations) for depot capacity and live EVSE and connector status — which bays are free, which are faulted — to plan charging windows and routing. See the [Locations](/components/charging/locations) component.

### Completed sessions

Each finished session becomes a CDR carrying the token and customer, so you can attribute cost and consumption to a driver, vehicle, or sub-fleet. Filter by the token or customer, then use the [Reporting and dashboards](/developers/reporting-and-dashboards) playbook to turn CDRs into reports. See the [Sessions and CDRs](/components/charging/sessions-and-cdrs) component.

## Best practices

* **Map your own IDs.** Set `externalId` on customers and a recognisable `label` on tokens, and join on `location.id` and `evseId` when reconciling with your system. See [Identifiers](/developers/identifiers).
* **Sync incrementally and page fully.** Pull only what changed and follow the cursor to the end, so a scheduled sync moves the new records rather than re-pulling the whole history each run. See [Filtering](/developers/filtering) and [Pagination](/developers/pagination).
* **Retry transient errors safely**, and don't retry a rejected request unchanged. See [Errors](/developers/errors).

<Warning>
  When a driver or vehicle leaves the fleet, **disable** the token to stop it charging. **Deleting** a token sets it inactive permanently — and its UID can't be reused for a new token — so reserve deletion for cases where you're sure.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Reporting and dashboards" icon="chart-column" href="/developers/reporting-and-dashboards">
    The retrieval patterns for turning charging data into reports.
  </Card>

  <Card title="Pylon" icon="gauge" href="/developers/pylon">
    Set up the Pylon integration.
  </Card>
</CardGroup>