Fleet API and events

You will be able to find every Fleet endpoint group, see which roles may call each one, and read the shape of the events Fleet writes for other systems. Delivery of events to outside systems arrives in Phase 9. Until then Dispatch writes each event to the durable outbox, so none is lost.

Before you start #

You need an API token. See integration-keys-and-scopes.
Fleet writes need dispatch_fleet in the licence; reads and exports stay open. See fleet-without-the-licence.
Every path below sits under /api/v1/fleet, unless it says otherwise.

Endpoint groups #

Check GET /fleet/status first to see whether writes are licensed.

Assets and meters: /assets, /assets/{id}, /assets/{id}/meters, /meters/{id}/correct.
Maintenance: /pm/board, /assets/{id}/pm, /pm/{id}/complete.
Fuel: /assets/{id}/fuel, /assets/{id}/fuel/economy.
Tyres: /assets/{id}/tyre-layout, /assets/{id}/tyres, /tyres, /tyres/{id}/fit, /tyres/{id}/remove, /tyres/{id}/readings.
Inspections and defects: /inspections, /defects, /defects/{id}/clear.
Trips: /trips, /trips/{id}/end.
Documents: /doc-types, /doc-types/seed, /documents, /documents/{id}/void.
Money: /expenses, /expenses/{id}/void, /advances, /advances/settle, /driver-pay, /assets/{id}/tco.
Stock by location: /stock-locations, /parts/{id}/stock, /parts/{id}/receive, /parts/{id}/transfer, /parts/{id}/consume.
Positions and alerts: /positions, /assets/{id}/positions, /live, /alerts, /alerts/run.
Import and export: /export/{what}, /import/{what}.

Role groups #

Each route belongs to a group. The owner can use every group.

Management (owner, manager, advisor, dispatcher): most reads, assets, schedules, tyres, documents, defects, expenses, advances and cost reports.
Driver phone (owner, manager, dispatcher, driver): meter readings, fuel fills, service completion, tyre readings, inspections, trips, positions and expense entry.
Shop (owner, manager, advisor, technician): the stock-by-location routes.
Owner and manager: /alerts/run and /import/{what}.

Settings used by Fleet sit outside /fleet: /settings/locale, /settings/fleet, /settings/tax-rates, /settings/tax-defaults.

Events #

Every event uses the envelope {event, created_at, data}. Inside data, money is an integer in minor units next to a currency code, and ids are strings. Each event has a unique key, so repeating a call never writes it twice.

Event	Written when
`expense.recorded`	An expense is recorded.
`expense.voided`	An expense is voided, with its reason.
`advance.issued`	An advance is issued to a person.
`advance.settled`	A person's open balance is settled.
`driver_pay.created`	A pay figure is recorded for a person and period.
`vendor.upserted`	A vendor is added or its name changes.
`invoice.issued`	An invoice is finalised. Each line carries `asset_ref`, the vehicle the invoice is for.
`part.consumed`	A part leaves stock. It carries `location_id`, `asset_ref` and `purpose`.

purpose is resale or internal; see stock-by-location. The wider event contract is in docs/platform/INTEGRATION.md, section 3.

Technical details

Events are written in the same transaction as the record they describe, through the outbox, and wait there for delivery.
Keys follow the pattern expense.recorded:{id} and invoice.issued:{invoice_id}; part.consumed uses a fresh key for each use.
expense.recorded data includes expense_id, asset_ref, asset_unit_no, kind, amount, currency, tax, incurred_on, paid_by, reimbursable and the person, vendor, work order, fuel log and trip references that apply.
invoice.issued data includes invoice_id, number, customer_ref, currency, issued_on, due_on, lines, total and job_id.
Writes accept an Idempotency-Key header; see idempotency.

If something goes wrong #

feature_not_licensed (403) or licence_read_only (403): see fleet-without-the-licence.
validation_failed (422): a field is missing or out of range; the answer names it under fields.
invalid_date (422): write dates as YYYY-MM-DD, date-times in ISO 8601.
conflict (409) and not_found (404): see api-errors-reference.

Accounting and finance

All apps. One device each.