developer quickstart

Your first delivery in five minutes

A clean REST API, signed webhooks and live WebSocket tracking. Everything below works against https://api.claritybite.com/api/v1 — the interactive OpenAPI reference lives at /docs on the API host.

1. Authentication

Server-to-server calls authenticate with an API key sent in the x-api-key header. Create keys in Dashboard → Settings → API keys — each key is scoped to your organization and can be revoked independently.

terminal — verify your key

# Keys look like fv_live_… (production) or fv_test_… (sandbox)
curl https://api.claritybite.com/api/v1/orders \
  -H "x-api-key: fv_live_xxxxxxxxxxxxxxxx"

Errors follow RFC 9457 application/problem+json; validation failures return 422 with a field-level errors map. All money values are minor units (paise).

2. Create an order

One call creates the order, and autoDispatch: true hands it straight to AI dispatch — rider assignment, customer WhatsApp notification and a branded tracking link included.

terminal — create + auto-dispatch

curl -X POST https://api.claritybite.com/api/v1/orders \
  -H "x-api-key: fv_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "brn_koramangala",
    "channel": "API",
    "customer": { "name": "Priya", "phone": "+919876543210" },
    "dropoff": {
      "addressLine1": "88, Koramangala 5th Block",
      "latitude": 12.9411,
      "longitude": 77.6169
    },
    "items": [
      { "name": "Veg Thali", "quantity": 2, "unitPrice": 24000 }
    ],
    "paymentMode": "COD",
    "autoDispatch": true
  }'

response — 201 Created

{
  "orderNumber": "FV-10003",
  "status": "CONFIRMED",
  "delivery": {
    "status": "PENDING",
    "trackingToken": "2b2e331ce43a81665a06fd55"
  }
} // share https://claritybite.com/t/<trackingToken> with your customer

3. Webhooks & signature verification

Subscribe to events like order.created, delivery.status_changed and delivery.delayed. Every delivery is signed so you can prove it came from FleetView:

header — on every webhook request

x-fleetview-signature: t=1750000000,v1=5257a869e7…
// v1 = HMAC-SHA256(secret, "<t>.<rawBody>")

verify.ts — Node / TypeScript

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(
  rawBody: string,      // exact bytes — do not JSON.parse first
  signature: string,    // x-fleetview-signature header
  secret: string,       // whsec_… from the dashboard
): boolean {
  const parts = Object.fromEntries(
    signature.split(",").map((p) => p.split("=")),
  );
  const { t, v1 } = parts;
  if (!t || !v1) return false;

  // Reject replays older than 5 minutes
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(v1, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Respond with a 2xx within 10 seconds; anything else is retried with exponential backoff. Verify against the raw request body — re-serialized JSON will not match the signature.

4. Real-time tracking

Anything with a tracking token can subscribe to live updates over Socket.IO — the same channel our branded tracking pages use. No API key required; the token is the credential.

tracking.ts — Socket.IO client

import { io } from "socket.io-client";

const socket = io("https://api.claritybite.com/tracking", {
  auth: { trackingToken: "2b2e331ce43a81665a06fd55" },
});

socket.on("status", (update) => {
  // PENDING → ASSIGNED → PICKED_UP → IN_TRANSIT → DELIVERED
  console.log("status:", update);
});

socket.on("rider.location", ({ latitude, longitude }) => {
  // live GPS — move your marker
});

Prefer polling? The same data is one unauthenticated GET away: GET /api/v1/track/:token. Dashboards can subscribe to the /dispatch namespace with a user JWT for branch-wide delivery and rider streams.

API access is included from the Growth plan

> fleetview init

Build on FleetView.

A REST API, signed webhooks and live WebSockets — with a sandbox key from day one of your free trial.

Start free trial See pricing