Dispatch API v1

Deliveries, driven from your own software

Your company already takes bookings through its RheoChat booking page. This is the same four operations — quote, book, track, cancel — behind an API key, so your website, your ERP or your ops tooling can run them directly.

What you can do#

Five endpoints, and nothing hidden behind them: an API booking creates exactly the delivery a web booking creates, priced by the same function, visible in the same dashboard, assigned to the same riders.

OperationEndpointUse it for
GET /quoteQuote a deliveryShowing a price before your customer commits.
POST /deliveriesBook a deliveryCreating the delivery and getting a tracking code.
GET /deliveries/{id}Retrieve a deliveryStatus, rider assignment and the full event timeline.
GET /deliveriesList deliveriesReconciliation and back-office screens.
POST /deliveries/{id}/cancelCancel a deliveryCalling off a delivery before a rider collects it.

Before you start#

  • An approved dispatch company on RheoChat. The API acts as your company: your vehicles, your pricing, your riders. A company that is not approved and active is refused with company_inactive.
  • An API key. The company owner mints one at rider.rheochat.com/<your-company>/admin/developers — sidebar → Developers → New key. Start with a test key; the full walkthrough is in Authentication.
  • Coordinates. Every call is priced from latitude and longitude, not from the address text. Geocode before you call, and send the address for the rider to read.
  • A server. A live key is a credential that moves money and sends a person across a city. It must never reach a browser, a mobile binary or a repository.

Quickstart#

Three calls, in test mode, priced exactly as production prices them and charging nobody. You can run all three before your company has a payout account.

1 — Ask what it costs

quote
curl "https://api.rheochat.com/api/v1/dispatch/quote?pickup_lat=9.8965&pickup_lng=8.8583&dropoff_lat=9.9285&dropoff_lng=8.8921&weight_kg=2" \
  -H "Authorization: Bearer rk_test_YOUR_KEY"

2 — Book it

The price is recalculated server-side, so the quote above is advisory and any amount in your request body is ignored. The Idempotency-Key header is what makes this call safe to retry.

book
curl -X POST "https://api.rheochat.com/api/v1/dispatch/deliveries" \
  -H "Authorization: Bearer rk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-attempt-1" \
  -d '{
    "pickup_name": "Mama Put Kitchen",
    "pickup_phone": "+2348012345678",
    "pickup_address": "12 Ahmadu Bello Way, Jos",
    "pickup_lat": 9.8965,
    "pickup_lng": 8.8583,
    "dropoff_name": "Amaka O.",
    "dropoff_phone": "+2348098765432",
    "dropoff_address": "5 Rwang Pam St, Jos",
    "dropoff_lat": 9.9285,
    "dropoff_lng": 8.8921,
    "item_description": "Jollof rice x2",
    "weight_kg": 2,
    "payment_method": "cod",
    "reference": "your-order-4821"
  }'

3 — Follow it

The response carries a tracking_code like DCAB12CD34. Use it — or the id — to read the delivery and its timeline.

track
curl "https://api.rheochat.com/api/v1/dispatch/deliveries/DCAB12CD34" \
  -H "Authorization: Bearer rk_test_YOUR_KEY"

The whole thing at once

// Not on npm yet — download the single file from /developers/sdk
import { RheoChatDispatch, withIdempotencyKey } from "./rheochat-dispatch";

const dispatch = new RheoChatDispatch({ apiKey: process.env.RHEOCHAT_API_KEY! });

// 1 — what will it cost?
const quote = await dispatch.quote({
  pickup:  { lat: 9.8965, lng: 8.8583 },
  dropoff: { lat: 9.9285, lng: 8.8921 },
  weightKg: 2,
});

// 2 — book it.
const delivery = await dispatch.createDelivery({
  pickup:  { name: "Mama Put Kitchen", phone: "+2348012345678",
             address: "12 Ahmadu Bello Way, Jos", lat: 9.8965, lng: 8.8583 },
  dropoff: { name: "Amaka O.", phone: "+2348098765432",
             address: "5 Rwang Pam St, Jos", lat: 9.9285, lng: 8.8921 },
  itemDescription: "Jollof rice x2",
  paymentMethod: "cod",
  reference: "your-order-4821",
  idempotencyKey: withIdempotencyKey("order-4821"),
});

// 3 — follow it.
const latest = await dispatch.getDelivery(delivery.tracking_code);
console.log(latest.status, latest.events);

Test mode is the place to start

A test key runs the same code path at the same prices, but never charges a card, pages a rider, records a settlement or sends an email. Read Test and live before you switch keys.

Conventions#

Everything the API does, it does the same way on every endpoint.

ConventionDetail
Base URLhttps://api.rheochat.com
AuthenticationBearer token: Authorization: Bearer rk_live_…
FormatJSON in, JSON out. Send Content-Type: application/json on POST.
MoneyWhole naira as numbers, never strings or kobo. currency is always NGN.
CoordinatesDecimal degrees. Nigeria only — anything outside is refused with 422.
TimestampsISO 8601 with timezone, UTC.
EnvironmentEvery response carries environment and livemode, so a log line says which world it happened in.
Request idEvery response carries request_id. Quote it in a support email and we can find the exact call.
CachingAll responses are Cache-Control: no-store.
every response carries these
{
  "id": "0f9a1c8e-6b2a-4f0d-9b7e-3c5a1d2e4f60",
  "tracking_code": "DCAB12CD34",
  "environment": "test",
  "livemode": false,
  "status": "pending",
  "request_id": "b6d3f7c2-2f41-4f7e-9c1a-0a5d6e8b4c11"
}

Limits, and what the API does not do yet#

Stated plainly, because planning around a feature that does not exist is more expensive than knowing it is missing.

  • A monthly booking allowance. Fifty live API bookings a month on the free plan, ten thousand on Pro; test mode is unlimited. See the allowance.
  • No webhooks. Status changes are not pushed to you. Poll the retrieve endpoint — a delivery in flight is worth a call every 30–60 seconds, and one at rest far less.
  • No filtering on the list endpoint. You can page by date, and that is all — filter by status or reference on your side.
  • No scheduled bookings. An API booking is for now, not for 6pm. Schedule on your side and call at the time you want the rider.
  • No multi-stop or shopper runs. Those exist in the dashboard, not yet in v1.

Where to go next#