"We have an API" is true of nearly every fleet platform. Whether that API is usable, documented, complete and stable enough to build on is a separate question, and it is answerable before you sign.
Evaluating an API before purchase
Ask for the documentation URL. If it is behind a sales gate, that is your first data point.
Then check:
| Check | What good looks like |
|---|---|
| Public documentation | Openly readable, with examples and error codes |
| Coverage | Every object you can edit in the UI is reachable via API |
| Authentication | OAuth 2.0 or API keys with scopes; not a username and password in a query string |
| Versioning | Explicit versions, published deprecation policy, minimum notice period |
| Rate limits | Documented, with headers showing your remaining quota |
| Pagination | Cursor-based, consistent across endpoints |
| Webhooks | Available for operational events, with retry and signature verification |
| Sandbox | A free test environment with realistic data |
| Changelog | Published, dated, with breaking changes flagged |
A platform that scores well here is telling you something about its engineering culture beyond the API itself.
The endpoints that matter for fleet work
Read-heavy
- Assets — list, filter by status and group, retrieve details and custom fields
- Odometer and engine hours — current and historical readings
- Work orders — with line-level labour and parts
- Maintenance schedules and due status
- Documents and expiry dates
- Drivers and assignments
- Fuel transactions
- Inspection results
Write
- Create and update assets
- Create work orders and defects
- Post odometer readings
- Upload documents
- Update assignments
Events (webhooks)
- Defect raised
- Work order status changed
- Vehicle status changed (off road / returned to service)
- Inspection failed
- Document approaching expiry
- Service due
Webhooks matter more than most buyers realise. Polling a REST API every five minutes for status changes is wasteful, slow and hits rate limits; a webhook delivers the event as it happens.
Authentication and secrets
- Prefer OAuth 2.0 client credentials with scoped tokens over long-lived API keys.
- One credential per integration, never one shared key for everything. Rotation and revocation become impossible otherwise.
- Store secrets in a secrets manager, not in configuration files or, worse, in the integration code.
- Set an expiry and a rotation schedule from day one; rotating a key that has been in production untouched for three years is an outage waiting to happen.
- Log authentication failures and alert on them — they are usually the first sign of an expired credential.
Designing an integration that lasts
Idempotency. Every write must be safe to retry. Use a client-generated idempotency key where the API supports it; where it does not, design a check-then-write with a natural key.
Backoff and retry. Exponential backoff with jitter on 429 and 5xx responses. Immediate aggressive retries turn a brief vendor issue into an outage on your side too.
Dead letter handling. Failed messages go to a queue a human reviews, not to a log file nobody reads.
Reconciliation. A daily job comparing record counts and key totals on both sides. This catches the silent partial failures that monitoring misses.
Schema tolerance. Ignore unknown fields rather than failing on them. Vendors add fields without notice; strict parsers break on release day.
Feature flags. Be able to disable an integration without a deployment when the vendor has an incident.
Rate limits and volume
Understand the limits before designing. Common patterns:
- Requests per minute per token
- Concurrent request caps
- Daily quotas on export-style endpoints
- Different limits for read and write
Design around them: bulk endpoints where available, incremental sync using a modified-since filter rather than full extracts, caching of slow-changing reference data, and scheduling heavy jobs outside your operational peak.
A full nightly extract of every asset is the usual culprit when a fleet hits its quota. Incremental sync is nearly always available and nearly always overlooked.
Questions readers send us
Should we build integrations ourselves or buy connectors? Buy standard connectors for standard systems — they are cheaper and supported. Build where the integration encodes something distinctive about your operation, and only if you can commit to maintaining it after the original developer moves on.
What happens to our integrations when the vendor upgrades? With a versioned API and a published deprecation policy, nothing immediate; you migrate within the notice period. Without versioning, upgrades break integrations without warning — which is why the versioning policy is a purchase criterion rather than a technical detail.
Is GraphQL better than REST for fleet data? It can reduce over-fetching on complex nested queries, but it is rarer in this market and adds client complexity. A well-designed REST API with filtering and sparse fieldsets is entirely adequate for fleet integration work.
How do we monitor integration health? Track success rate, latency, records processed and queue depth, with alerts on deviation from normal rather than only on hard failure. Add the daily reconciliation report — most real failures are partial, not total, and only reconciliation catches those.
Can we get historical data out through the API? Usually, but often slowly and subject to quotas. For bulk historical extraction, ask whether the vendor offers a data export or warehouse feed instead. Attempting a full history extract through an operational API is a common way to trip rate limits and irritate your vendor's support team.
