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
- Search with route, date, time and passengers. You get offers with a
offer_idvalid for 15 minutes. - Book the offer with passenger details. The price is taken from your prepaid wallet.
- The company confirms and assigns a driver. You receive webhooks for each step, including driver name, phone and plate.
- 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 /search
Request body
| route_id | Route from /routes. Or use hourly. |
| hourly | { "city": "Madinah", "hours": 4 } |
| date | YYYY-MM-DD |
| time | HH:MM pick-up time |
| passengers | Number of people |
| bags | Large bags |
Request
{
"route_id": "R3",
"date": "",
"time": "10:00",
"passengers": 3,
"bags": 3
}Response
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.confirmed | Company accepted the booking |
| booking.driver_assigned | Driver name, phone, vehicle and plate |
| booking.driver_en_route | Driver left for pick-up |
| booking.completed | Trip finished |
| booking.cancelled | Cancelled 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_request | Missing or wrong field. detail says which. |
| 401 unauthorized | Key missing, wrong or disabled. |
| 402 insufficient_wallet | Top up your wallet with the company. |
| 409 offer_unavailable | The vehicle was just booked. Search again. |
| 429 rate_limited | Slow down; retry after the Retry-After seconds. |