Skip to main content
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 Spirii Connect, it grants access to every endpoint you’ll use here — and a working understanding of charge keys, 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 charge key is how a driver (an app or RFID) or a vehicle (Autocharge) authenticates to charge. Registering a charge key grants it access to charge; each charge key 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 charge key and customer, so you can attribute every kWh back to a driver, vehicle, or sub-fleet.
In the API these are tokens — /v2/tokens and /v2/token-groups. The docs call them charge keys to match Spirii Connect; the object is the same.
If a depot is a public location and you want to keep it to your fleet, a charge key group can restrict charging there to a chosen set of charge keys — but for a private depot the charge key alone is enough, so it isn’t part of the setup below.

​
Set up the fleet

1

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

Register drivers' and vehicles' charge keys

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 charge key in the platform registers that credential so Spirii recognises it and authenticates charging against it. You’ll typically:
  • register RFID charge keys the fleet already holds, by their chip UID,
  • create virtual charge keys for drivers authenticating through an app,
  • register vehicle (Autocharge) charge keys by a vehicle’s MAC address or VIN.
Link each charge key to the customer that should be billed with customerId.
See Create a charge key and the Charge keys component for the three charge key types and their fields.

​
Verify

Have a provisioned charge key start a charge at the depot. The session appears in Transactions, and once it ends a CDR is generated carrying that charge key 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 charge key 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 charge key and customer, so you can attribute cost and consumption to a driver, vehicle, or sub-fleet. Filter by the charge key 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 charge keys, 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 charge key to stop it charging. Deleting a charge key sets it inactive permanently — and its UID can’t be reused for a new charge key — so reserve deletion for cases where you’re sure.

​
Next steps

Reporting and dashboards

The retrieval patterns for turning charging data into reports.

Price pylon

Set up the price pylon integration.