5-Minute Quickstart

Get your API key, calculate live rates, and book your first parcel delivery.

This tutorial walks you through setting up API authentication, estimating shipping rates, and booking your first parcel delivery.

Step 1: Obtain Your Secret API Key 1. Create an account on Tumr and sign in. 2. Create a key with `POST /api/v1/auth/api-keys/` using your session JWT (the dispatch dashboard's API Keys screen wraps the same endpoint). 3. Copy the key — it is shown once at creation. Keys are prefixed `tumr_live_` (production) or `tumr_test_` (test mode).

Include this key in the Authorization header of every API request: ``http Authorization: Bearer tumr_test_...

Step 2: Compare Delivery Rates Submit pickup and destination coordinates to evaluate available fulfillment options:

curl -X POST https://api.tumr.app/api/v1/rates/ \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup_latitude": 6.4281,
    "pickup_longitude": 3.4219,
    "dropoff_latitude": 6.5244,
    "dropoff_longitude": 3.3792,
    "package_weight_kg": 2.5,
    "declared_value": 15000.00,
    "pickup_country": "NG"
  }'

Sample Response: ``json { "direct_distance_km": "11.62", "is_rider_coverable": true, "recommended_mode": "marketplace", "currency": "NGN", "rates": [ { "rate_id": "rate_mkp_exp_8820ab12", "rate_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxmaWxsbWVudF9tb2RlIjoibWFya2V0cGxhY2UiLCJzZXJ2aWNlX2xldmVsIjoiRVhQUkVTUyIsInRvdGFsIjoiMjQ1MC4wMCJ9...", "fulfillment_mode": "marketplace", "service_level": "EXPRESS", "service_name": "Express Rush Delivery", "provider": "Tumr Marketplace Rider Network", "total": "2450.00", "currency": "NGN", "distance_km": "11.62", "estimated_duration_minutes": 29, "badge": "express / On-Demand", "breakdown": { "base_fare": "1500.00", "distance_fee": "800.00", "weight_fee": "150.00", "value_surcharge": "0.00", "protection_fee": "0.00" } } ], "marketplace_rates": [...], "carrier_rates": [...], "pickup_points": [] }

Step 3: Book the Delivery Create the shipment and pass the signed `rate_token` returned from the rates step to lock in the quoted fare:

curl -X POST https://api.tumr.app/api/v1/shipments/ \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_reference": "ORDER-2026-0924",
    "customer_name": "Ada Okafor",
    "customer_phone": "+2348012345678",
    "pickup_address": "12 Admiralty Way, Lekki Phase 1, Lagos",
    "pickup_latitude": 6.4281,
    "pickup_longitude": 3.4219,
    "dropoff_address": "45 Allen Avenue, Ikeja, Lagos",
    "dropoff_latitude": 6.5244,
    "dropoff_longitude": 3.3792,
    "package_weight_kg": 2.5,
    "declared_value": 15000.00,
    "pickup_country": "NG",
    "rate_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxmaWxsbWVudF9tb2RlIjoibWFya2V0cGxhY2UiLCJzZXJ2aWNlX2xldmVsIjoiRVhQUkVTUyIsInRvdGFsIjoiMjQ1MC4wMCJ9...",
    "package_description": "Electronics (Headphones)"
  }'

Step 4: Share Tracking & OTP with Customer The customer receives an automated SMS with the shipment's tracking number (format `AKR-XXXXXXXX`). They can check status on the public tracking page — `https://tumr.app/en/track/` — by entering the tracking number and their recipient phone number.

When the courier arrives at the destination, the customer provides their secure 6-digit delivery OTP to confirm receipt and finalize escrow settlement.

5-Minute Quickstart

Step 2: Compare Delivery Rates Submit pickup and destination coordinates to evaluate available fulfillment options:

Step 3: Book the Delivery Create the shipment and pass the signed rate_token returned from the rates step to lock in the quoted fare:

Step 4: Share Tracking & OTP with Customer The customer receives an automated SMS with the shipment's tracking number (format AKR-XXXXXXXX). They can check status on the public tracking page — https://tumr.app/en/track/ — by entering the tracking number and their recipient phone number.

Step 3: Book the Delivery Create the shipment and pass the signed `rate_token` returned from the rates step to lock in the quoted fare:

Step 4: Share Tracking & OTP with Customer The customer receives an automated SMS with the shipment's tracking number (format `AKR-XXXXXXXX`). They can check status on the public tracking page — `https://tumr.app/en/track/` — by entering the tracking number and their recipient phone number.