Partner API preview · example responses use demo data Demo guide
REST · JSON · v1

Umrah Transport API

Sell car-with-driver transfers in Makkah, Madinah and Jeddah from licensed local companies. One API for search, booking, status updates and cancellation.

Authentication

Send your key in the Authorization header. Sandbox keys start with sf_test_; sandbox bookings never reach the transport companies. Live keys start with sf_live_.

curl https://api.safarfleet.com/transport/v1/routes \
  -H "Authorization: Bearer sf_test_xxxxxxxxxxxx"

Base URL: https://api.safarfleet.com/transport/v1 · rate limit 60 requests per minute per key · prices in SAR, times in Saudi time (UTC+3).

Booking flow

  1. Search with route, date, time and passengers. You get offers with a offer_id valid for 15 minutes.
  2. Book the offer with passenger details. The price is taken from your prepaid wallet.
  3. The company confirms and assigns a driver. You receive webhooks for each step, including driver name, phone and plate.
  4. Your customer can also get WhatsApp messages from the company if you pass notify_customer: true.

Try it

Runs a search on the demo data, exactly as the API would answer.

// response appears here

GET /routes

All bookable routes. Use id in search.

POST /bookings

{
  "offer_id": "off_C1_sedan_R3_…",
  "passenger": {
    "name": "Ahmed Raza",
    "phone": "+923001234567",
    "email": "ahmed@example.com",
    "country": "PK"
  },
  "flight": "SV 723",
  "dropoff_note": "Swissotel Makkah",
  "extras": { "child_seat": 1, "meet_greet": true },
  "notify_customer": true,
  "your_reference": "AGY-55102"
}
{
  "booking_id": "TR482913",
  "status": "pending",
  "company": { "name": "Madinah Demo Transport", "phone": "+966500000100" },
  "price": { "net": 250, "extras": 30, "total": 280, "currency": "SAR" },
  "wallet_balance": 9720,
  "cancellation": { "free_until": "T10:00:00+03:00", "fee_pct_after": 50 }
}

GET /bookings/{id}

Current status with driver and vehicle once assigned.

PUT /bookings/{id}/cancel

Cancels and returns the refund to your wallet according to the company's policy.

{
  "booking_id": "TR482913",
  "status": "cancelled",
  "cancellation_fee": 0,
  "refund": 280,
  "currency": "SAR"
}

Webhooks

We POST to your URL when a booking changes. Verify the X-Signature header (HMAC-SHA256 of the body with your webhook secret).

booking.confirmedCompany accepted the booking
booking.driver_assignedDriver name, phone, vehicle and plate
booking.driver_en_routeDriver left for pick-up
booking.completedTrip finished
booking.cancelledCancelled by you, the customer or the company, with refund
{
  "event": "booking.driver_assigned",
  "booking_id": "TR100301",
  "driver": { "name": "Rizwan Ahmed", "phone": "+966500000103", "languages": ["Urdu","Arabic","English"] },
  "vehicle": { "model": "GMC Yukon XL 2024", "color": "Black", "plate": "1190 KSA" },
  "pickup_at": "T09:00:00+03:00"
}

Errors

400 bad_requestMissing or wrong field. detail says which.
401 unauthorizedKey missing, wrong or disabled.
402 insufficient_walletTop up your wallet with the company.
409 offer_unavailableThe vehicle was just booked. Search again.
429 rate_limitedSlow down; retry after the Retry-After seconds.