Overview
Company trips come in two types:
- Trip Routes - Template routes that can be booked multiple times
- Public Trips - Scheduled trips with assigned driver/vehicle where passengers book individual seats
Get Company Trip Details
Retrieve detailed information about a specific company trip route.
curl -X GET "https://api.masareagles.com/api/companies/{companyId}/trips/{tripId}" \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
/api/companies/{companyId}/trips/{tripId}
Response
Total number of times this route can be booked
Number of active bookings
Whether route is currently bookable
Assigned driver ID (if any)
Date route becomes available
{
"id": "comptrip_abc123",
"companyId": "comp_xyz789",
"fromCityId": "city_riyadh",
"fromCity": "Riyadh",
"fromLatitude": 24.7136,
"fromLongitude": 46.6753,
"fromAddress": "King Khalid International Airport",
"toCityId": "city_jeddah",
"toCity": "Jeddah",
"toLatitude": 21.5433,
"toLongitude": 39.1728,
"toAddress": "King Abdulaziz International Airport",
"availabilityCount": 10,
"currentBookings": 3,
"remainingAvailability": 7,
"isAvailableForBooking": true,
"price": 250.00,
"currency": "SAR",
"vehicleTypeId": "vtype_luxury",
"assignedDriverId": "drv_comp456",
"status": "Active",
"isActive": true,
"availabilityDate": "2026-03-15T00:00:00Z",
"createdAtUtc": "2026-03-01T10:00:00Z",
"updatedAtUtc": "2026-03-10T14:30:00Z"
}
Update Company Trip
Update details of a company trip route.
curl -X PUT "https://api.masareagles.com/api/companies/{companyId}/trips/{tripId}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"price": 275.00,
"availabilityCount": 15,
"isActive": true,
"assignedDriverId": "drv_comp789"
}'
Endpoint
/api/companies/{companyId}/trips/{tripId}
Request Body
Updated availability count
Whether to activate or deactivate the route
Response
Indicates if update succeeded
Updated trip route details (same structure as Get Company Trip Details)
Delete Company Trip
Delete a company trip route. Only possible if there are no active bookings.
curl -X DELETE "https://api.masareagles.com/api/companies/{companyId}/trips/{tripId}" \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
/api/companies/{companyId}/trips/{tripId}
Response
Indicates if deletion succeeded
{
"success": true,
"message": "تم حذف مسار الرحلة بنجاح"
}
Search Company Trips
Search for company trip routes with filters.
curl -X GET "https://api.masareagles.com/api/companies/{companyId}/trips/search?fromCity=Riyadh&toCity=Jeddah&isActive=true" \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
/api/companies/{companyId}/trips/search
Query Parameters
Filter by destination city
Response
Array of matching company trip routes
Get Public Trip Details
Get details of a specific public trip for passengers.
curl -X GET "https://api.masareagles.com/api/public-trips/{tripId}" \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
/api/public-trips/{tripId}
Response
Request success indicator
Public trip details
Currently available seats
Array of stop locations with coordinates and times
{
"success": true,
"data": {
"id": "pubtrip_xyz789",
"companyId": "comp_abc123",
"companyName": "Eagle Express Transport",
"companyLogo": "https://cdn.example.com/companies/eagle.png",
"companyRating": 4.7,
"fromCity": "Makkah",
"fromCityId": "city_makkah",
"fromAddress": "Makkah Central Station",
"fromLatitude": 21.4225,
"fromLongitude": 39.8262,
"toCity": "Madinah",
"toCityId": "city_madinah",
"toAddress": "Madinah Bus Terminal",
"toLatitude": 24.5247,
"toLongitude": 39.5692,
"departureTimeUtc": "2026-03-20T06:00:00Z",
"arrivalTimeUtc": "2026-03-20T10:30:00Z",
"pricePerSeat": 80.00,
"currency": "SAR",
"totalSeats": 45,
"availableSeats": 32,
"bookedSeats": 13,
"driverId": "drv_comp456",
"driverName": "Hassan Al-Otaibi",
"driverPhoto": "https://cdn.example.com/drivers/hassan.jpg",
"driverRating": 4.9,
"vehicleId": "veh_bus789",
"vehicleModel": "Mercedes Tourismo",
"vehicleImageUrl": "https://cdn.example.com/vehicles/tourismo.jpg",
"description": "Direct express service with rest stop",
"status": "Scheduled",
"stops": [
{
"id": "stop_123",
"location": "Bahra",
"latitude": 22.8167,
"longitude": 39.5833,
"stopTimeUtc": "2026-03-20T08:00:00Z",
"stopOrder": 1,
"description": "15-minute break"
}
]
}
}
Get Company Bookings
Retrieve all bookings for a company’s trips.
curl -X GET "https://api.masareagles.com/api/companies/{companyId}/bookings?status=Pending&page=1&pageSize=20" \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
/api/companies/{companyId}/bookings
Query Parameters
Filter by booking status (Pending, Confirmed, Cancelled, etc.)
Filter by specific trip ID
Results per page (default: 20)
Response
Array of booking objects with passenger, trip, and payment details
{
"bookings": [
{
"id": "bkg_comp123",
"tripId": "comptrip_abc",
"bookingNumber": "BKNG-2026-001234",
"passengerId": "psng_xyz",
"passengerName": "Fatima Al-Harbi",
"passengerPhone": "+966501234567",
"status": "Pending",
"paymentStatus": "Pending",
"amountPaid": 250.00,
"currency": "SAR",
"tripDateTime": "2026-03-15T08:00:00Z",
"pickupLatitude": 24.7136,
"pickupLongitude": 46.6753,
"pickupAddress": "King Khalid Airport Terminal 1",
"dropoffLatitude": 21.5433,
"dropoffLongitude": 39.1728,
"dropoffAddress": "King Abdulaziz Airport",
"createdAtUtc": "2026-03-10T09:30:00Z"
}
],
"totalCount": 1,
"page": 1,
"pageSize": 20
}