Use this page to understand the recommended call order, request shapes, and what is live vs stubbed. Base path:
Otp:UseStaticCode=true (Development),
verify with code 1234. Production uses real SMS — enter the code you receive.
POST /api/app/auth/otp/request
→ save challengeId
POST /api/app/auth/otp/verify
→ save data.token + data.refreshToken
(new phone → isFirst: true)
POST /api/app/auth/signup/complete
with Bearer — set fullName (skippable)
GET /api/app/profile then
POST /api/app/profile/addresses
POST /api/app/profile/payment-methods
→ save id for booking
GET /api/app/home
→ activeTrip (in-progress ride or null) +
latestTrips (up to 5 recent completed/canceled)
POST /api/app/rides/compare
→ pick an offerId before it expires
POST /api/app/rides
with offerId + paymentMethodRefId
GET /rides/{id} · cancel while Processing ·
rate only after Completed
GET /api/app/ads?screen=Home ·
GET /api/app/pages ·
GET /api/app/pages/about-us
POST /api/app/auth/refresh then
POST /api/app/auth/logout (last)
Runs against this host. Token is kept in sessionStorage only.
Ready.
| Area | Method / path | Status | Notes |
|---|---|---|---|
| Auth | POST /api/app/auth/otp/request | live | { phoneCode, phone, purpose: "login" } |
| Auth | POST /api/app/auth/otp/verify | live | Returns flat token (not accessToken) |
| Auth | POST /api/app/auth/signup/complete | live | Bearer USER · optional |
| Auth | POST /api/app/auth/refresh | live | { refreshToken } → TokenPair |
| Auth | POST /api/app/auth/logout | live | Bearer · revokes refresh tokens |
| Profile | GET/PATCH /api/app/profile | live | + addresses, payment-methods, devices, prefs |
| Rides | GET /api/app/home | live | Bearer · activeTrip + latestTrips (see sample below) |
| Rides | POST /api/app/rides/compare | live | Riyadh sample coords work well |
| Rides | POST /api/app/rides | live | { offerId, paymentMethodRefId } |
| Rides | GET /api/app/rides?status=&page=&pageSize= | live | Paginated ride history · optional RideStatus filter |
| Rides | GET/cancel/rating /api/app/rides/{id} | live | Status rules apply |
| Eats discover/order | GET restaurants · POST orders… | stub 501 | Phase 1: not implemented yet |
| Eats | GET /api/app/eats/orders/{id} | partial | Works when an order exists |
| Promo | POST /api/app/promo/validate | live | Try code BALORA10 / EATS15 |
| Loyalty | GET /api/app/loyalty/balance | live | Bearer required |
| Support | POST /api/app/issues | live | Link to ride/order id |
| Contact | POST /api/contact-us | live | Public · no auth |
| Content | GET /api/app/ads · /api/app/pages | live | Public |
| Countries | GET /api/app/countries | live | Public · phone picker (dial, length, start digit) |
| Geo | GET /api/app/geo/autocomplete|reverse | stub 501 | Until Places vendor is wired |
| Attachments | POST /api/attachments | live | multipart · Bearer |
{
"phoneCode": "+966",
"phone": "500000010",
"purpose": "login"
}
{
"challengeId": "<from request>",
"code": "1234",
"deviceToken": "dev-device-token",
"deviceType": "android"
}
{
"pickupLat": 24.7136,
"pickupLng": 46.6753,
"pickupText": "Riyadh - Central",
"dropoffLat": 24.7743,
"dropoffLng": 46.7386,
"dropoffText": "Riyadh - West",
"rideCategory": "standard",
"passengerCount": 1
}
{
"offerId": "<from compare.offers[0].offerId>",
"paymentMethodRefId": 1,
"noteToDriver": "Gate A",
"promoCode": "BALORA10"
}
GET /api/app/home{
"success": true,
"data": {
"activeTrip": {
"id": 42,
"providerId": 1,
"providerName": "Uber",
"providerRideRef": "uber-ride-abc123",
"status": "Arriving",
"source": "Integration",
"rideType": "UberX",
"passengerCount": 2,
"pickupText": "12 Nile St, Cairo",
"dropoffText": "Cairo International Airport",
"fareEstimate": { "amount": 185.50, "currency": "EGP" },
"finalFare": null,
"driver": {
"name": "Ahmed Hassan",
"photoUrl": "https://cdn.example.com/drivers/ahmed.jpg",
"vehicle": "Toyota Corolla",
"plate": "ABC 1234",
"rating": 4.8,
"lat": 30.0442,
"lng": 31.2357
},
"promoApplied": {
"code": "BALORA10",
"discount": { "amount": 18.55, "currency": "EGP" }
},
"requestedAt": "2026-07-27T12:15:30Z"
},
"latestTrips": [
{
"id": 38,
"providerId": 1,
"providerName": "Uber",
"providerRideRef": "uber-ride-xyz789",
"status": "Completed",
"source": "Integration",
"rideType": "UberX",
"passengerCount": 1,
"pickupText": "Maadi, Cairo",
"dropoffText": "Downtown Cairo",
"fareEstimate": { "amount": 95.00, "currency": "EGP" },
"finalFare": { "amount": 92.50, "currency": "EGP" },
"driver": null,
"promoApplied": null,
"requestedAt": "2026-07-25T18:40:00Z"
}
]
},
"message": null
}
When no ride is in progress, activeTrip is null.
latestTrips returns up to 5 terminal rides
(Completed, RiderCanceled, DriverCanceled, NoDriversAvailable).