FuelAtlas.
Join the beta
FAFuelAtlasDevelopers

Developers / Quickstart

Quickstart: TMS

Provision a fleet, add vehicles, stream locations, and read fuel guidance — end to end.

This is the full path for a TMS that manages many fleets: from a partner key to live fuel guidance for a truck, in about fifteen calls. Run it against the sandbox first (fa_test_ key) — every step is identical in production.

You'll use a partner key, which manages many fleets and selects the acting fleet per request with the FA-Fleet header. See Authentication for the key model.

0. What you need

A partner key from the Developer Console with these scopes: fleets:manage, vehicles:manage, locations:write, guidance:read, guidance:manage, usage:read. Confirm it:

cURL
curl https://api.fuelatlas.com/v1/me \
  -H "Authorization: Bearer $FA_KEY"

The response shows partner, your scopes, and your plan. If partner is null, you have a company key, not a partner key — you can skip fleet provisioning and go straight to step 2 (your fleet is implicit).

1. Provision a fleet

Create a fleet for your customer. This is a partner-level call — no FA-Fleet header. The response's id (flt_…) is the fleet you'll act on for everything else.

curl -X POST https://api.fuelatlas.com/v1/fleets \
  -H "Authorization: Bearer $FA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Bolt Carriers", "external_ref": "CUST-4471", "contact_email": "ops@bolt.example", "timezone": "America/Chicago" }'

Store external_ref as your own stable reference for the fleet — you can look it up by that later.

2. Add vehicles

Now act on the fleet: every fleet-scoped call carries FA-Fleet: <flt_id>. Identify each vehicle by your own external_ref (required) so you never have to store our ids. Set tank_size_gallons and estimated_mpg — guidance needs them to project fuel.

curl -X POST https://api.fuelatlas.com/v1/vehicles \
  -H "Authorization: Bearer $FA_KEY" \
  -H "FA-Fleet: $FLEET_ID" \
  -H "Content-Type: application/json" \
  -d '{ "external_ref": "TRUCK-042", "name": "Unit 042", "vin": "1FUJGLDR9CLBP8834", "tank_size_gallons": 200, "estimated_mpg": 6.5, "license_plate": "TN-8842J" }'

If a vehicle with the same VIN already exists in the fleet, the call returns 200 with merged_with_existing: true (it linked your external_ref to the existing vehicle) instead of 201. Repeat for each truck.

3. Stream locations

Push GPS breadcrumbs in batches — this is the fuel that powers everything downstream. Send every 1–5 minutes per vehicle, and include fuel_level_percent. Identify vehicles by the external_ref you set.

cURL
curl -X POST https://api.fuelatlas.com/v1/locations \
  -H "Authorization: Bearer $FA_KEY" \
  -H "FA-Fleet: $FLEET_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      { "external_ref": "TRUCK-042", "latitude": 35.1495, "longitude": -90.0490,
        "recorded_at": "2026-07-06T15:04:05Z", "fuel_level_percent": 34.0, "speed_mph": 62 }
    ]
  }'

Check the per-item results — a rejected row with code: "unknown_vehicle" means that external_ref isn't created yet. See Push locations.

4. Set a destination

Bind the truck to where it's headed. Guidance takes over from here.

cURL
curl -X POST https://api.fuelatlas.com/v1/vehicles/$VEHICLE_ID/guidance \
  -H "Authorization: Bearer $FA_KEY" \
  -H "FA-Fleet: $FLEET_ID" \
  -H "Content-Type: application/json" \
  -d '{ "destination": { "latitude": 41.8781, "longitude": -87.6298, "name": "Chicago DC" }, "min_arrival_fuel_percent": 15 }'

5. Read the recommendation

Poll the guidance object (or subscribe via webhooks). When phase is stop_recommended, stops[0] is the cheapest on-route stop — fully costed, with a driver-ready reason.

cURL
curl https://api.fuelatlas.com/v1/vehicles/$VEHICLE_ID/guidance \
  -H "Authorization: Bearer $FA_KEY" \
  -H "FA-Fleet: $FLEET_ID"

Surface stops[0].station.name, gallons_to_buy, and net price (price_usd_per_gallon − discount_usd_per_gallon) to your dispatcher or driver. When the driver commits, acknowledge the stop; if they can't take it, skip it. Full field reference in Autoguide.

6. Report savings

After trucks fuel at recommended stops, roll up the value you delivered:

cURL
curl "https://api.fuelatlas.com/v1/reports/savings?from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer $FA_KEY" \
  -H "FA-Fleet: $FLEET_ID"

You get fleet totals, an adherence rate, and per-vehicle savings — the numbers to put in front of your customer.

You're integrated

That's the whole loop: provision → vehicles → locations → guidance → savings. Everything else (trips, fuelings, webhooks) layers on top of it. Next:

  • Webhooks — stop polling; get pushed guidance and arrival events.
  • Autoguide — the full guidance object reference.
  • Errors — the problem+json envelope for robust handling.