Introduction
The Novil API lets a transportation management system (TMS), or any other system that knows about dispatched loads, push routes into Novil and read back the vehicles, drivers and fuel plans behind them.
A pushed route becomes a draft route in Novil. When the truck arrives at the route’s first stop, Novil builds the fuel plan (where to stop, how many gallons to buy, at what price) and sends it to the driver, exactly as it does for routes that arrive through a telematics or TMS integration. Your side of the integration is small: push each load once, and read the route back when you want its status or its plan.
Who it is for
Section titled “Who it is for”- TMS vendors and integrators wiring dispatch into Novil for a shared customer.
- Fleets with their own engineering that dispatch from an in-house system.
- Anyone who wants to read the fuel plans Novil produced, for reporting or for showing them alongside the load.
If your fleet’s dispatch already reaches Novil through a supported telematics or TMS connection, you do not need this API to get fuel plans. Use it when routes live somewhere Novil cannot see.
Base URL
Section titled “Base URL”All requests go to the Novil app:
https://app.novilfleet.comEvery path in this documentation is relative to that origin, and every path in the current version starts with /v1.
Conventions
Section titled “Conventions”JSON in, JSON out. Request bodies are JSON and must be sent with Content-Type: application/json. Successful responses are application/json. Errors are application/problem+json with a stable code field; see Errors.
Timestamps are RFC 3339. Send timestamps with an offset, for example 2026-09-14T06:00:00-05:00 for 6 AM Central. Novil returns timestamps in UTC with a Z suffix, so the same moment comes back as 2026-09-14T11:00:00Z. The company’s time zone is reported by GET /v1/me if you need to display times the way dispatchers see them.
Identifiers are strings. Route, vehicle and driver ids are opaque strings assigned by Novil. Treat them as stable and do not parse them.
Lists are paged. List endpoints accept limit (1 to 100, default 25) and offset (default 0) and return { "data": [...], "total": n, "limit": n, "offset": n }.
Authentication is a bearer key. Every request carries Authorization: Bearer nvl_live_.... Keys are created under Settings › API Keys in the Novil app; see Authentication.
The API is path-versioned. This documentation covers /v1. Additive changes ship without a version bump; anything that would break a client gets a new path. See Versioning.
Resources
Section titled “Resources”| Resource | What it holds |
|---|---|
| Keys | GET /v1/me describes the key a request is authenticated with: its company, scopes, environment and rate limit. |
| Routes | Dispatch routes pushed from your TMS. Create or update, retrieve, list and cancel. A route carries its own fuel plan once Novil has built one: the fuel stops, with gallons, prices and estimated arrivals. |
| Vehicles | Read-only access to the fleet’s vehicles, for checking how a unit number or VIN will match. |
| Drivers | Read-only access to drivers, for checking how a name will match. |
The Endpoints page lists every path, and the API reference renders the full OpenAPI contract with request and response schemas.
Where to go next
Section titled “Where to go next”- Authentication explains keys, scopes and the live and sandbox environments.
- The Quickstart walks from a new key to a fuel plan in six requests.
- Pushing routes from a TMS covers idempotency, the route lifecycle and cancellation in depth.