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.
| Operation | Endpoint | Use it for |
|---|---|---|
GET /quote | Quote a delivery | Showing a price before your customer commits. |
POST /deliveries | Book a delivery | Creating the delivery and getting a tracking code. |
GET /deliveries/{id} | Retrieve a delivery | Status, rider assignment and the full event timeline. |
GET /deliveries | List deliveries | Reconciliation and back-office screens. |
POST /deliveries/{id}/cancel | Cancel a delivery | Calling 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
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.
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.
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
Conventions#
Everything the API does, it does the same way on every endpoint.
| Convention | Detail |
|---|---|
| Base URL | https://api.rheochat.com |
| Authentication | Bearer token: Authorization: Bearer rk_live_… |
| Format | JSON in, JSON out. Send Content-Type: application/json on POST. |
| Money | Whole naira as numbers, never strings or kobo. currency is always NGN. |
| Coordinates | Decimal degrees. Nigeria only — anything outside is refused with 422. |
| Timestamps | ISO 8601 with timezone, UTC. |
| Environment | Every response carries environment and livemode, so a log line says which world it happened in. |
| Request id | Every response carries request_id. Quote it in a support email and we can find the exact call. |
| Caching | All responses are Cache-Control: no-store. |
{
"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.