Developers

Build on the FleetRails API

REST, JSON, predictable webhooks. Sandbox keys in minutes.

Quickstart Auth Shipments Warehouse Webhooks API Keys Limits Status

From key to first shipment in four steps

Create your workspace (it comes with a sandbox).
Generate an API key in Settings → Developers (or POST /api/v1/admin/api-keys).
POST /api/v1/shipments with your pickup and drop-off zones.
Poll the shipment, or subscribe to the order.delivered webhook.

# create a shipment
curl https://api.fleetrails.com/api/v1/shipments \
  -H "Authorization: Bearer fr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"pickup":{"zone":"yaba"},"dropoff":{"zone":"lekki"},
       "customer":{"name":"Ada","phone":"+234…"}}'

Keys scoped to your workspace

Live and test keys are separate — sandbox data never touches production.
Rotate keys anytime from the console; old keys stay valid for 24 hours.
Treat secret keys like passwords: server-side only, never in browsers or mobile apps.

API Key Management

Admin endpoints for managing keys programmatically:

GET/api/v1/admin/api-keysList all keys

POST/api/v1/admin/api-keysCreate a key (returns secret once)

GET/api/v1/admin/api-keys/:keyIdGet key details

POST/api/v1/admin/api-keys/:keyId/rotateRotate key (new secret)

DELETE/api/v1/admin/api-keys/:keyIdRevoke key

Shipments (Orders)

Endpoints available at both /api/v1/orders and /api/v1/shipments — they are aliases.

POST/api/v1/shipmentsCreate a shipment

GET/api/v1/shipmentsList (paginated, filterable)

GET/api/v1/shipments/:idRetrieve one shipment

PUT/api/v1/shipments/:id/statusUpdate status

PUT/api/v1/shipments/:id/assign-riderAssign rider

GET/api/v1/shipments/:id/nearest-ridersFind nearest riders

POST/api/v1/shipments/:id/evidence/photoUpload proof photo

GET/api/v1/shipments/:id/labelDownload label PDF

GET/api/v1/shipments/:id/audit-logsAudit trail

POST/api/v1/shipments/estimatePrice estimate

POST/api/v1/shipments/bulkBulk upload (CSV)

Warehouse / Inventory

GET/api/v1/inventoryList inventory (paginated, filterable)

GET/api/v1/inventory/movementsMovement ledger

POST/api/v1/inventory/reserveReserve stock

POST/api/v1/inventory/unreserveRelease reservation

POST/api/v1/inventory/damageMark as damaged

Webhooks

Subscribe to events in the console. Every delivery is signed so you can verify it came from us.

Webhook Management (per API key)

POST/api/v1/api-keys/:apiKeyId/webhooksRegister webhook URL

GET/api/v1/api-keys/:apiKeyId/webhooksGet webhook config

PUT/api/v1/api-keys/:apiKeyId/webhooksUpdate webhook

PUT/api/v1/api-keys/:apiKeyId/webhooks/enabledEnable/disable

DELETE/api/v1/api-keys/:apiKeyId/webhooksDelete webhook

POST/api/v1/api-keys/:apiKeyId/webhooks/rotate-secretRotate signing secret

GET/api/v1/api-keys/:apiKeyId/webhooks/statsDelivery stats

GET/api/v1/api-keys/:apiKeyId/webhooks/deliveriesDelivery logs

POST/api/v1/api-keys/:apiKeyId/webhooks/testSend test event

Event Types (Order Lifecycle)

Dispatched to tenant webhooks when events occur:

order.created order.status_changed order.assigned order.picked_up order.delivered order.payment_confirmed order.failed_delivery order.returned order.cancelled

Payload Example

# POST to your webhook URL
FR-Signature: t=1724508000,v1=5f8a…
Content-Type: application/json

{
  "eventType": "order.delivered",
  "timestamp": 1724508000123,
  "apiKeyId": "ak_live_…",
  "tenantId": "tn_…",
  "data": {
    "orderId": "ord_…",
    "trackingCode": "FR-48213",
    "status": "DELIVERED",
    "recipientName": "Ada O.",
    "deliveredAt": "2026-08-24T13:58:04Z"
  }
}

Verify Signatures

# HMAC-SHA256 of (timestamp + "." + body) using webhook secret
# FR-Signature: t=,v1=
const payload = timestamp + "." + body;
const expected = crypto.createHmac("sha256", secret)
  .update(payload).digest("hex");
if (expected !== signature) throw new Error("Invalid signature");

API Keys

Manage keys via the console or programmatically (see Auth section).

Keys are tenant-scoped — each workspace has its own keys.
Prefixes: fr_live_ (production), fr_test_ (sandbox).
Permissions: keys inherit the creating admin's permissions (currently API_KEYS_MANAGE scope).
Rotation: POST /api/v1/admin/api-keys/:keyId/rotate returns new secret; old key valid for 24h grace period.

Rate limits

120 requests/minute per key (burst to 150). Auth endpoints: 10 req/min. Returns 429 with Retry-After header.

Errors

Errors are JSON with a consistent shape:

{
  "error": {
    "code": "zone_not_found",
    "message": "Zone 'xyz' not found",
    "details": { "zone": "xyz" }
  }
}

Common codes: zone_not_found, insufficient_balance, order_not_found, unauthorized, rate_limited, validation_failed.

Environments & status

Live API	`api.fleetrails.com/api/v1`
Sandbox API	`sandbox.api.fleetrails.com/api/v1`
Tracking links	`trk.fleetrails.com`
Status page	status.fleetrails.com

Rate Limits

Applied per API key:

120 requests/minute per key (burst to 150)
Auth endpoints: stricter limits (10 req/min)
Returns 429 with Retry-After header (seconds)

Get a sandbox key today

Book a demo and we’ll flip the switch on your workspace.

Start free Request access