Fleet management

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 — created by an operator in Connect, it grants access to every endpoint you’ll use here — and a working understanding of 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

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.

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 for the billing and financial fields to include if you use Spirii’s financial services.

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.

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 and the Tokens component for the three token types and their fields.

Verify

Have a provisioned token start a charge at the depot. The session appears in 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.

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 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 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 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 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 playbook to turn CDRs into reports. See the 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.
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 and Pagination.
Retry transient errors safely, and don’t retry a rejected request unchanged. See Errors.

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.

Get started

Mechanics

Playbooks

Fleet management

Before you start

How the pieces fit

Set up the fleet

Verify

Track charging

Live sessions and state of charge

Depot status

Completed sessions

Best practices

Next steps

Reporting and dashboards

Pylon

​Before you start

​How the pieces fit

​Set up the fleet

​Verify

​Track charging

​Live sessions and state of charge

​Depot status

​Completed sessions

​Best practices

​Next steps

Reporting and dashboards

Pylon

Before you start

How the pieces fit

Set up the fleet

Verify

Track charging

Live sessions and state of charge

Depot status

Completed sessions

Best practices

Next steps