Live Tracking & OTP Verification

Public tracking endpoints, universal carrier tracking timeline, and recipient delivery confirmation workflows.

POST

Look up a shipment's status using the public tracking number plus the recipient's phone number as an identity check.

Authentication: Public / Unauthenticated

Request Body Fields

Field	Type	Requirement	Description
shipment_id	string	Required	Tracking number (e.g. "AKR-83491054") or Shipment UUID.
phone	string	Required	Recipient phone number for identity challenge validation.

Request ExampleHTTPS Live Endpoint

curl -X POST https://api.tumr.app/api/v1/track/ \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_id": "AKR-83491054",
    "phone": "+2348012345678"
  }'

Response Payload

201 Created

application/json

{
  "id": "76495b28-1004-4b52-9fe1-d64e8e5ab190",
  "tracking_number": "AKR-83491054",
  "status": "IN_TRANSIT",
  "customer_name": "Ada Okafor",
  "pickup_address": "12 Admiralty Way, Lekki Phase 1, Lagos",
  "dropoff_address": "45 Allen Avenue, Ikeja, Lagos",
  "rider_email": "[email protected]",
  "created_at": "2026-08-14T10:15:00Z",
  "updated_at": "2026-08-14T10:30:10Z"
}

GET

Universal public tracking timeline for Tumr shipments and carrier-partner parcels. Accepts a tracking number, parcel ID, waybill number, or shipment UUID.

Authentication: Public / Unauthenticated

Request ExampleHTTPS Live Endpoint

curl -X GET https://api.tumr.app/api/v1/tracking/AKR-83491054/

Response Payload

200 OK

application/json

{
  "parcel_id": "PRC-48210",
  "waybill_number": "AKR-83491054",
  "tracking_number": "AKR-83491054",
  "status": "IN_TRANSIT",
  "current_status": "Transit to Ikeja Terminal",
  "origin": { "code": "YBA", "name": "Yaba Central Hub", "latitude": 6.4281, "longitude": 3.4219 },
  "destination": { "code": "IKJ", "name": "Ikeja Terminal", "latitude": 6.5244, "longitude": 3.3792 },
  "created_date": "14 Aug 2026",
  "expected_date": "15 Aug 2026",
  "picked_up_at": "14 Aug 2026, 10:40AM",
  "estimated_delivery": {
    "remaining_distance_km": 8.2,
    "estimated_minutes": 20,
    "eta_display": "~20 mins",
    "rider_latitude": 6.4901,
    "rider_longitude": 3.4012,
    "rider_name": "Emeka Obi",
    "rider_phone": "+2348012345678"
  },
  "timeline": [
    { "title": "In Transit", "status": "IN_TRANSIT", "timestamp": "14 Aug 2026, 02:30PM" },
    { "title": "Parcel Created - Yaba Central Hub", "status": "PENDING", "timestamp": "14 Aug 2026, 10:15AM" }
  ]
}

POST

Confirm delivery at the dropoff point. The assigned rider submits current GPS coordinates together with the 6-digit OTP provided by the recipient. On success the shipment transitions to COMPLETED and escrow funds are settled. OTP verification is capped at 5 attempts.

Authentication: Rider / Carrier JWT

Request Body Fields

Field	Type	Requirement	Description
latitude	decimal	Required	Rider GPS latitude at the dropoff.
longitude	decimal	Required	Rider GPS longitude at the dropoff.
otp	string	Optional	6-digit numeric OTP provided by the recipient.

Request ExampleHTTPS Live Endpoint

curl -X POST https://api.tumr.app/api/v1/shipments/76495b28-1004-4b52-9fe1-d64e8e5ab190/verify/ \
  -H "Authorization: Bearer YOUR_RIDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 6.5244, "longitude": 3.3792, "otp": "491823"}'

Response Payload

201 Created

application/json

{
  "id": "76495b28-1004-4b52-9fe1-d64e8e5ab190",
  "tracking_number": "AKR-83491054",
  "status": "COMPLETED",
  "completed_at": "2026-08-14T11:05:12Z",
  "escrow_status": "RELEASED",
  "escrow_amount": "0.00"
}

Previous TopicStorefront & Orders

Next TopicWebhooks & Event Streams