Fleetr API Integration Guide
Bring your fleet information into the systems your business already uses.
Last updated: .
Fleetr provides a REST API for developers who want to integrate tracking data into their own systems.
Documentation
Full API documentation is available at fleetr.co.ke/api/docs, powered by interactive Swagger UI. You can explore endpoints and test requests directly from the browser.
Account Integration Tokens
For a business system connecting to your fleet, open Account → Integrations → API access. Account API access is a plan-gated feature; the page shows whether it is included.
- Open API access with an authorised account user.
- Create a token for the integration and choose an available role appropriate for its work.
- Copy the displayed token and store it securely in the receiving system. Its full value is shown only once.
- Send it in the request header:
Authorization: Bearer YOUR_TOKEN. - Use the token controls to rotate credentials or revoke access when the integration is no longer needed.
These tokens belong to the account and use a role to determine access. They are separate from a person's normal browser session. Never put a real token in a public page, screenshot, or support message. Rotation invalidates the old token immediately; update the consuming system with the replacement.
For application login flows and endpoint-specific requirements, follow the interactive API documentation. A valid token does not bypass account permissions, plan restrictions, or subscription access checks.
Create Cost Centres From Another System
Use POST /api/cost-centers with a management-capable account token, explicit numeric X-Account-ID and a persistent UUID Idempotency-Key. The first successful request returns 201; the same normalized request and key return the original result with 200, preventing duplicates after a lost response. A key reused with different values returns 409; conflicting existing names or codes return 422 without adopting another record. Follow Create Cost Centres Through the Fleetr API for request fields, account permissions and safe retries.
Keep Zones in Sync From a Connected App
Dispatchr can create, update and delete its zones with POST /api/integrations/geofences and PUT/DELETE /api/integrations/geofences/{id}. Use an account API token, an explicit numeric X-Account-ID and X-Vertical: dispatchr. Retries are safe: a zone is identified by its external_ref, so the same zone sent again updates it instead of adding a second one. Each write reaches the tracking server immediately. A zone watches every vehicle in the account and is read-only in Fleetr. Entries and exits come back through event forwarding as geofence.enter and geofence.exit with geofence_external_ref. See Keep Connected-App Zones in Sync for fields, limits and errors.
Calculate Routes and Visiting Orders
Schoolrun, Dispatchr and other clients can call POST /api/nav/plan with an origin, optional destination, stop coordinates and an optimize choice. Use true for a suggested visiting order; reorder the stops in the calling app and use false for directions through that exact order. Google/OSRM accept up to 25 intermediate stops; Mapbox accepts up to 10 optimised or 23 ordered stops. The response includes the stop order, road distance, driving time, geometry and directions. This is a stateless calculation: the client owns its plan and Fleetr creates no saved route or GPS journey. See Route Planning for Connected Apps for authentication, provider selection, limits, pricing references and error handling.
Precise Journey Times for Playback
GET /api/vehicles/{vehicle}/journeys includes additive start_at_iso and end_at_iso fields with UTC offsets and exact seconds. Use these precise instants to bound playback or synchronize journey timestamps. The existing start_at and end_at fields keep their legacy minute-resolution format for mobile compatibility. The response timezone identifies the account's display timezone; it does not change the UTC instants.
Event Forwarding
Open Account → Integrations → Event forwarding to manage configured event destinations. Where your permissions and plan allow it, you can add or edit a destination, enable or disable forwarding, send a test, rotate its secret, or delete it.
Coordinate the destination configuration with the receiving system's administrator. Use a test to confirm that it accepts deliveries before depending on forwarding for an operational workflow. If you rotate a secret, update the receiver as well. Event forwarding connects systems; personal email, SMS, and push preferences are managed under notification settings.
For a recorded-journey mirror, explicitly select journey.updated and journey.deleted. These signed notifications cover newly saved journeys, final measurements, corrections, restoration and retirement, including replacements whose old and new journey IDs differ. They carry journey_id, vehicle_id, a per-journey revision and deleted, not a complete journey. Deduplicate by envelope event_id, tolerate out-of-order delivery, and refetch GET /vehicles/{vehicle}/journeys in the explicit account context. Keep your own operational records separate from the source mirror. See Keep Recorded Journeys in Sync for examples, opt-in requirements and recovery limits.
What's Available
The API covers vehicles, devices, real-time locations, journeys, drivers, geofences, fleet statistics, maintenance, insurance, and more. Refer to the API Documentation for complete details.
Make Your First API Request
Use the production base URL https://fleetr.co.ke/api. Start with a read-only request to confirm authentication and account selection before implementing changes in an external system.
GET /api/vehicles HTTP/1.1
Host: fleetr.co.ke
Authorization: Bearer YOUR_ACCOUNT_API_TOKEN
Accept: application/json
X-Account-ID: YOUR_ACCOUNT_ID
Replace the placeholders with your integration token and account ID. X-Account-ID selects the account on endpoints that support account context; it does not grant access to an account the token cannot use. Without this header, those endpoints can use the user's first associated account, so set it explicitly in a multi-account integration.
Follow response pagination and the endpoint's documented filters. Do not assume that a single response contains an entire fleet or every historical record. Use JSON request bodies and Content-Type: application/json for endpoints expecting JSON writes.
Customer API Capability Map
Paths below are relative to /api. Each operation still requires its applicable role, subscription, and feature access.
| Capability | Example endpoint | What an integration can do |
|---|---|---|
| Fleet vehicles | GET /vehicles | Discover accessible vehicles and their identifiers |
| Vehicle details | GET /vehicles/{vehicle} | Read a selected vehicle's record |
| Vehicle creation and updates | POST /vehicles, PUT /vehicles/{vehicle} | Maintain vehicle records with editing permission |
| Latest location | GET /vehicles/{vehicle}/location | Retrieve the available position for a vehicle |
| Journeys and mileage | GET /vehicles/{vehicle}/journeys, GET /vehicles/{vehicle}/mileage | Read recorded activity |
| Device management | GET /vehicles/{vehicle}/devices | Inspect attached trackers; documented write endpoints attach, edit, remove, and set primary |
| Device commands | GET /vehicles/{vehicle}/devices/{device}/commands | Review commands and use supported command actions with the required permissions |
| Sharing links | GET /vehicles/{vehicle}/share-links | List links; documented POST and DELETE operations create and revoke them |
| Drivers | GET /drivers | Read profiles; documented actions manage profiles and assignments |
| Maintenance | GET /vehicles/{vehicle}/maintenance | Read service records and use documented record, update, and completion actions |
| Insurance | GET /vehicles/{vehicle}/insurance | Read policies and use documented maintenance and AKI-verification actions |
| Geofences | GET /geofences, GET /geofences/alerts | Read boundaries and recorded alerts |
| Fleet summaries | GET /fleet/overview, GET /fleet/mileage, GET /fleet/events, GET /fleet/trends | Retrieve permitted fleet summaries and activity |
| Telemetry | GET /telemetry/metrics, GET /vehicles/{vehicle}/telemetry, GET /telemetry | Read metrics such as fuel used, fuel level, odometer and battery voltage over a period, per interval or at an instant |
| Notifications | GET /notifications, GET /notifications/preferences | Read the inbox and manage supported preference actions |
| Reference data | GET /device-makes, GET /vehicle-types, GET /license-types | Populate supported device and vehicle choices; authentication requirements vary |
| Support | GET /tickets, POST /tickets | Read accessible support tickets or submit an issue |
Use the interactive API reference and OpenAPI specification for exact fields, filters, response shapes, and endpoint-specific account behaviour. Not every browser workflow has a matching public write endpoint; for example, the listed geofence API routes provide reading and alerts, while the web application supplies its creation workflow.
Manage Integration Credentials
Give each integration a recognisable token name and choose Account Member for permitted viewing or Account Administrator when the integration genuinely needs its account-management capabilities. There is a maximum of 10 account API tokens; revoke an unused one before creating another if the limit is reached.
The full token is displayed once. If you lose it, rotate it and update the consuming system. Review last-used information when deciding whether a token is still needed. Revocation ends access for that credential; it does not delete the fleet records the integration previously read.
Handle API Errors
| Response | What to check |
|---|---|
| 401 | Missing, expired, revoked, or otherwise invalid authentication |
| 402 | Account subscription access; read the returned access level and billing action |
| 403 | Role, account membership, feature eligibility, or selected account |
| 404 | Resource ID, route, and whether the resource is available to this request |
| 422 | Submitted field values and the validation errors in the response |
| 429 | Request rate; back off before retrying |
| 5xx | Temporary service failure; record the time and request context and retry cautiously |
Do not blindly retry writes or vehicle commands: check whether the first request took effect before repeating it. Keep tokens out of logs and send support a redacted request, response status, and time if a problem persists.
Fleetr Help Centre