API Documentation — AnchorRide

Introduction

The AnchorRide API lets you fetch shipping rates and create prepaid deliveries through Okada's own network of active riders. Every order is a real delivery — the same rider pool that handles ordinary Okada rides.

The base URL for all API requests is:

https://okada-backend.onrender.com/api/anchorride/v1

All request and response bodies are JSON. All amounts are in Nigerian Naira (NGN).

Authentication

Every request to the API is authenticated with your API key, sent as a Bearer token in the Authorization header:

Authorization: Bearer ar_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Get your API key from your dashboard after signing up. Keys are only ever shown once, at the moment they're created — store it somewhere safe.

You can create additional keys or revoke a key at any time from your dashboard without affecting your other keys.

Get a rate

POST /rates

Returns a real fare quote for a pickup and dropoff, based on actual road distance — the exact same fare an order created with these coordinates will be charged.

Request body

Field	Type	Description
pickup	object	Required. `{ latitude, longitude }`
dropoff	object	Required. `{ latitude, longitude }`

Example request

POST /rates
Content-Type: application/json

{
  "pickup": { "latitude": 7.398657, "longitude": 3.9495069 },
  "dropoff": { "latitude": 7.417546, "longitude": 3.964764 }
}

Example response

200 OK

{
  "fare": 1233,
  "currency": "NGN",
  "distanceKm": 4.88,
  "durationMin": 11
}

Create an order

POST /orders

Creates a real delivery and debits the fare from your wallet balance immediately. There's no separate confirmation step — call /rates first to see the fare, then call this endpoint to actually book it at that price.

Request body

Field	Type	Description
pickup	object	Required. `{ latitude, longitude }`
dropoff	object	Required. `{ latitude, longitude }`
pickupLabel	string	Optional. Human-readable pickup address, shown to the driver.
dropoffLabel	string	Optional. Human-readable dropoff address, shown to the driver.
details	string	Optional. Notes about the package for the driver.
externalReference	string	Optional. Your own order ID, returned back to you on every lookup and webhook so you can match it to your own system.

Example request

POST /orders
Content-Type: application/json

{
  "pickup": { "latitude": 7.398657, "longitude": 3.9495069 },
  "dropoff": { "latitude": 7.417546, "longitude": 3.964764 },
  "pickupLabel": "Warehouse, Iwo Road",
  "dropoffLabel": "12 Bodija Estate",
  "externalReference": "ORDER-1001"
}

Example response

201 Created

{
  "orderId": 2,
  "rideId": 66,
  "externalReference": "ORDER-1001",
  "status": "requested",
  "fare": 1233,
  "currency": "NGN",
  "distanceKm": 4.88,
  "dropoffPin": "2360"
}

dropoffPin is a 4-digit code the driver will ask for when they arrive at the dropoff address, to confirm the right person received the package. Pass this along to your customer however you normally communicate with them — an order confirmation SMS, an email receipt, or in your app.

Insufficient balance

If your wallet balance doesn't cover the fare, the order is not created and no charge occurs:

402 Payment Required

{
  "message": "Insufficient wallet balance.",
  "required": 1233,
  "available": 500
}

Get order status

GET /orders/:id

Looks up an order by its AnchorRide order ID (the orderId returned when you created it).

Example response

200 OK

{
  "orderId": 2,
  "externalReference": "ORDER-1001",
  "status": "in_progress",
  "fare": 1233,
  "distanceKm": 4.88,
  "createdAt": "2026-08-23T06:15:09.367Z"
}

Possible status values

Status	Meaning
requested	Order created, waiting for a driver.
matched	A driver has been assigned.
driver_en_route	Driver is heading to the pickup address.
in_progress	Package picked up, driver en route to dropoff.
completed	Delivered — the driver confirmed the dropoff PIN.
cancelled	Order was cancelled.

Order status events

Register a webhook URL from your dashboard to be notified automatically whenever one of your orders changes status, instead of polling GET /orders/:id.

Event types

Event	Fires when
order.driver_assigned	A driver accepts the order.
order.driver_en_route	Driver is heading to pickup.
order.picked_up	Package picked up.
order.delivered	Package delivered and PIN confirmed.
order.cancelled	Order was cancelled.

Payload

POST https://your-server.com/your-webhook-path
Content-Type: application/json
X-AnchorRide-Signature: 8f2a91c3...

{
  "event": "order.picked_up",
  "orderId": 2,
  "externalReference": "ORDER-1001",
  "status": "in_progress",
  "timestamp": "2026-08-23T06:57:14.221Z"
}

Your endpoint should respond with any 2xx status to acknowledge receipt. Deliveries are logged in your dashboard so you can see what was sent and whether it succeeded.

Verifying signatures

Every webhook request includes an X-AnchorRide-Signature header — an HMAC-SHA256 hash of the raw request body, signed with your webhook secret (shown once when you set your webhook URL). Verify it to confirm a request genuinely came from AnchorRide.

Node.js example

const crypto = require("crypto");

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return signature === expected;
}

Compute the signature over the exact raw request body — not a re-serialized copy of the parsed JSON, which can produce different bytes (key order, whitespace) and fail to match.

Errors

Errors return a JSON body with a message field describing what went wrong.

Status	Meaning
400	Missing or invalid request fields.
401	Missing, invalid, or revoked API key.
402	Insufficient wallet balance.
404	Order not found.
500	Something went wrong on our end. Safe to retry.