API documentation

Quickstart

1. Create an account, open Developers in the console and create an API key. It starts with dk_ and is shown once.
2. Add a rider. The response includes that rider’s token, which their app uses.

   curl https://YOUR-DOMAIN/api/v1/workers \
     -H "Authorization: Bearer $FLEETIT_KEY" -H "Content-Type: application/json" \
     -d '{ "name": "Tendai Moyo", "phone": "+263771234567", "vehicle": "motorbike" }'

3. Create a delivery. Dispatch starts looking for a rider at once.

   curl https://YOUR-DOMAIN/api/v1/jobs \
     -H "Authorization: Bearer $FLEETIT_KEY" -H "Content-Type: application/json" \
     -H "Idempotency-Key: order-1042" \
     -d '{
       "pickup": {
         "lat": -17.7572, "lng": 31.0853,
         "name": "Rustic Crust", "address": "Borrowdale Village"
       },
       "dropoff": {
         "lat": -17.7450, "lng": 31.1000,
         "name": "Tari", "phone": "+263771000002", "address": "12 Pendennis Rd"
       },
       "cash_to_collect": 2000,
       "external_ref": "order-1042"
     }'

4. Give the customer the tracking_url from the response, and set a webhook to hear about each step.

Authentication

Send a bearer token on every request: Authorization: Bearer <token>. There are two kinds.

Keep API keys on your server. Never put one in a mobile app or a web page: anyone who has it can act as you. Keys cannot create other keys or change your team; that needs an owner signed in to the console.

Conventions

• JSON in and out. Send Content-Type: application/json with a body.
• Money is an integer in minor units: 2000 means $20.00.
• Times on jobs and riders are RFC 3339 strings in UTC (2026-11-12T10:15:00Z). Webhook and tracking timestamps are Unix seconds.
• Coordinates are WGS84 decimal degrees, lat then lng. Out-of-range values are rejected.
• Ids are UUIDs that sort by creation time.
• Lists return newest first. Pass the response’s next_before as before to get the next page.

Errors

Errors use standard status codes and always have this body. Branch on code, show message to a person.

{ "error": { "code": "invalid_transition", "message": "a job that is picked_up cannot be cancelled" } }

Idempotency

Networks fail after the server has acted. To make POST /v1/jobs safe to retry, send an Idempotency-Key header: any string up to 200 characters that is unique per order, such as your order number. The first request creates the job and answers 201. Any later request with the same key answers 200 with that same job and creates nothing.

Rate limits

Each API key may make 1,200 requests a minute and each rider token 600. Beyond that you get 429 with a Retry-After header giving the seconds until the minute rolls over. Limits are per token, so one busy integration does not slow another. Prefer webhooks to polling.

Job lifecycle

A job moves forward through these states. failed and cancelled are the other two ways it can end.

You can cancel, or put a job back in the queue, until the rider has picked the goods up. After that the job can only be delivered or failed by the rider, so goods are never stranded with no job attached.

How a rider is chosen. Every second, all waiting jobs are matched to nearby riders together, in the pairing with the least total waiting. Riders are found by map hexagon around the pickup, timed by road, and ruled out if they are off duty, full, or would exceed their cash limit. A rider with room for two can be given a second order from the same pickup if it barely delays the first customer. If the goods will not be ready for a while (set ready_at, or let the system learn it per pickup place), the job is held so the rider arrives about when they are.

Webhooks

Set one HTTPS address in Console → Developers (or PUT /v1/webhook) and we POST every job event to it. Use Send test event to check your endpoint, and the delivery log to see what your server answered.

Events

job.created, job.offered, job.assigned, job.unassigned, job.at_pickup, job.picked_up, job.at_dropoff, job.delivered, job.failed, job.cancelled, and job.no_rider (sent once if nobody has taken a job after two minutes). The test button sends ping.

{
  "id": 48213,
  "type": "job.delivered",
  "job_id": "0196f3c2-6d1e-7c41-9a55-0d7f2b8e4a10",
  "created_at": 1794480000,
  "data": { "job": { "id": "0196f3c2-…", "state": "delivered", "cash_collected": 2000, "…": "the full Job object" } }
}

Delivery rules

• Answer with any 2xx within 5 seconds. Do slow work after you answer.
• Anything else is retried with growing gaps (10 s, 20 s, 40 s … up to an hour) for 12 attempts.
• Delivery is at least once and not strictly ordered. De-duplicate on id, and treat the higher id as newer.

Verify the signature

Every request carries X-FleetIt-Signature: t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256 of "<t>.<raw body>" using your signing secret. Compute it over the raw bytes you received, before parsing, and reject requests whose t is more than five minutes old.

// Node.js (Express)
import crypto from "node:crypto";

app.post("/dispatch-events", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("x-fleetit-signature") ?? "";
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", process.env.FLEETIT_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const match = v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
  if (!fresh || !match) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  // … handle event.type, de-duplicating on event.id …
  res.sendStatus(204);
});

# Python (Flask)
import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/dispatch-events")
def dispatch_events():
    parts = dict(p.split("=", 1) for p in request.headers.get("X-FleetIt-Signature", "").split(",") if "=" in p)
    t, v1 = parts.get("t", "0"), parts.get("v1", "")
    expected = hmac.new(os.environ["FLEETIT_WEBHOOK_SECRET"].encode(),
                        f"{t}.".encode() + request.get_data(), hashlib.sha256).hexdigest()
    if abs(time.time() - int(t)) > 300 or not hmac.compare_digest(v1, expected):
        abort(400)
    event = request.get_json()
    # … handle event["type"], de-duplicating on event["id"] …
    return "", 204

Building a rider app

A rider’s app talks to the /v1/worker/… endpoints with that rider’s token. The whole loop is:

1. Go on duty: POST /v1/worker/duty with {"on_duty": true}.
2. Send positions every 5 to 10 seconds: POST /v1/worker/locations. Buffer fixes when offline and send up to 200 at once. A rider who has not been heard from for 90 seconds stops receiving offers. The response lists any jobs this upload marked as arrived.
3. Check for an offer: GET /v1/worker/offers. A rider has at most one at a time, with a countdown. Customer contact details are held back until they accept.
4. Accept or decline: POST /v1/worker/offers/{id}/accept. A 409 offer_gone means it expired or went elsewhere.
5. Follow the plan: GET /v1/worker/plan returns the stops in the order to visit them, including both pickups first when two orders are stacked.
6. Confirm hand-overs: POST /v1/worker/jobs/{id}/progress with picked_up, then delivered (with proof and the cash collected) or failed with a reason. Arrivals are detected from position, so no tap is needed for those.

Offers are fetched by polling today; ask every few seconds while on duty.

Quotes and pricing

POST /v1/quotes with a pickup and drop-off returns the delivery fee, the road distance and how soon a rider could collect, without creating anything. Call it at checkout.

The fee is (fee_base + fee_per_km × km) × multiplier. The multiplier is 1.0 while free riders within about ten minutes of the pickup cover the orders waiting there, and rises in steps of 0.05 toward your surge_max as the shortfall grows. Set surge_max to 1 to switch it off. All three are in Console → Settings or PATCH /v1/settings.

Customer tracking

Every job has a tracking_url. Send it to the customer by SMS or WhatsApp: it opens a page with the delivery’s status, the rider on a map and the time to arrival. It needs no sign-in, and never shows phone numbers or amounts.

To build tracking into your own site or app, call GET /v1/track/{token} with the token at the end of that link. It is public and may be called from a browser on any site.

API reference

All 35 operations, generated from the OpenAPI description this server publishes.

Objects