Create Driver Trip Creates a new trip listing by a driver. The trip includes origin, destination, departure time, pricing, and available seats.
curl -X POST "https://api.masareagles.com/api/trips" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{ "from": "Riyadh", "fromLatitude": 24.7136, "fromLongitude": 46.6753, "fromAddress": "King Fahd Road", "fromDescription": "Near Faisaliah Tower", "to": "Jeddah", "toLatitude": 21.5433, "toLongitude": 39.1728, "toAddress": "Tahlia Street", "toDescription": "Near Red Sea Mall", "departureTimeUtc": "2026-03-15T08:00:00Z", "arrivalTimeUtc": "2026-03-15T16:00:00Z", "availableSeatCount": 3, "price": 150.00, "currency": "SAR", "vehicleId": "veh_abc123", "driverId": "drv_xyz789", "description": "Comfortable highway trip with AC", "stops": [ { "location": "Buraydah", "latitude": 26.3260, "longitude": 43.9751, "address": "Buraydah Central", "stopTimeUtc": "2026-03-15T10:00:00Z", "stopOrder": 1, "description": "Rest stop - 15 minutes" } ] }'
Endpoint Request Body Departure city/location name (max 200 characters)
Latitude coordinate of departure location
Longitude coordinate of departure location
Detailed address of departure point (max 500 characters)
Additional description or landmark for departure (max 500 characters)
Destination city/location name (max 200 characters)
Latitude coordinate of destination
Longitude coordinate of destination
Detailed address of destination (max 500 characters)
Additional description or landmark for destination (max 500 characters)
Trip departure date and time in UTC (ISO 8601 format)
Expected arrival date and time in UTC (ISO 8601 format)
Number of available seats (1-1000)
Price per seat (must be greater than 0)
Currency code (e.g., “SAR”, “USD”) - max 20 characters
ID of the vehicle to be used for the trip
ID of the driver offering the trip
Trip description and additional notes (max 1000 characters)
Array of intermediate stops along the route Stop location name (max 200 characters)
Latitude coordinate of stop
Longitude coordinate of stop
Detailed address of stop (max 500 characters)
Expected stop time in UTC
Order of stop in route (must be greater than 0)
Stop description (max 500 characters)
Response Indicates if the trip was created successfully
Success or error message in Arabic
Trip details object Number of available seats
Trip status (e.g., “Scheduled”, “InProgress”, “Completed”)
Array of stop objects with location details
Success Response
Validation Error
{ "success" : true , "message" : "تم إنشاء الرحلة بنجاح" , "data" : { "id" : "trip_abc123xyz" , "from" : "Riyadh" , "fromLatitude" : 24.7136 , "fromLongitude" : 46.6753 , "fromAddress" : "King Fahd Road" , "to" : "Jeddah" , "toLatitude" : 21.5433 , "toLongitude" : 39.1728 , "toAddress" : "Tahlia Street" , "departureTimeUtc" : "2026-03-15T08:00:00Z" , "arrivalTimeUtc" : "2026-03-15T16:00:00Z" , "availableSeatCount" : 3 , "reservedSeatCount" : 0 , "totalSeats" : 3 , "price" : 150.00 , "currency" : "SAR" , "currencyCode" : "SAR" , "vehicleId" : "veh_abc123" , "driverId" : "drv_xyz789" , "description" : "Comfortable highway trip with AC" , "status" : "Scheduled" , "stops" : [ { "id" : "stop_123" , "location" : "Buraydah" , "latitude" : 26.3260 , "longitude" : 43.9751 , "address" : "Buraydah Central" , "stopTimeUtc" : "2026-03-15T10:00:00Z" , "stopOrder" : 1 , "description" : "Rest stop - 15 minutes" } ], "createdAtUtc" : "2026-03-10T10:30:00Z" } }
Create Company Trip Route Creates a new trip route for a transportation company. This creates a template route that can be booked multiple times. Each booking creates an independent trip instance.
curl -X POST "https://api.masareagles.com/api/companies/{companyId}/trips" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{ "fromCityId": "city_riyadh", "fromCity": "Riyadh", "fromLatitude": 24.7136, "fromLongitude": 46.6753, "fromAddress": "King Khalid International Airport", "toCityId": "city_dammam", "toCity": "Dammam", "toLatitude": 26.4207, "toLongitude": 50.0888, "toAddress": "King Fahd International Airport", "availabilityCount": 10, "price": 200.00, "currency": "SAR", "vehicleTypeId": "vtype_luxury", "assignedDriverId": "drv_comp123", "availabilityDate": "2026-03-15T00:00:00Z" }'
Endpoint /api/companies/{companyId}/trips
Request Body Origin city name (max 255 characters)
Detailed origin address (max 500 characters)
Destination city identifier
Destination city name (max 255 characters)
Detailed destination address (max 500 characters)
Number of times this route can be booked (1-1000). Each booking decrements this count.
Trip price (0.01 - 999999.99)
Currency code (default: “SAR”, max 10 characters)
Vehicle type identifier for this route
Driver assigned to this route
Date when this route becomes available for booking
Response Indicates if trip route was created successfully
Company trip route details Unique trip route identifier
Detailed trip route information Number of current bookings
Whether route is open for booking
{ "success" : true , "message" : "تم إنشاء مسار الرحلة بنجاح" , "data" : { "tripId" : "comptrip_abc123" , "message" : "تم إنشاء مسار الرحلة بنجاح" , "trip" : { "id" : "comptrip_abc123" , "companyId" : "comp_xyz789" , "fromCityId" : "city_riyadh" , "fromCity" : "Riyadh" , "fromLatitude" : 24.7136 , "fromLongitude" : 46.6753 , "fromAddress" : "King Khalid International Airport" , "toCityId" : "city_dammam" , "toCity" : "Dammam" , "toLatitude" : 26.4207 , "toLongitude" : 50.0888 , "toAddress" : "King Fahd International Airport" , "availabilityCount" : 10 , "currentBookings" : 0 , "remainingAvailability" : 10 , "isAvailableForBooking" : true , "price" : 200.00 , "currency" : "SAR" , "vehicleTypeId" : "vtype_luxury" , "assignedDriverId" : "drv_comp123" , "status" : "Active" , "isActive" : true , "availabilityDate" : "2026-03-15T00:00:00Z" , "createdAtUtc" : "2026-03-10T10:30:00Z" , "updatedAtUtc" : "2026-03-10T10:30:00Z" } } }
Create Company Public Trip Creates a scheduled public trip where passengers book individual seats. Driver and vehicle are assigned at creation time.
curl -X POST "https://api.masareagles.com/api/companies/{companyId}/public-trips" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{ "driverId": "drv_comp456", "vehicleId": "veh_bus789", "fromCityId": "city_makkah", "fromCity": "Makkah", "fromLatitude": 21.4225, "fromLongitude": 39.8262, "fromAddress": "Makkah Central Station", "toCityId": "city_madinah", "toCity": "Madinah", "toLatitude": 24.5247, "toLongitude": 39.5692, "toAddress": "Madinah Bus Terminal", "seatCount": 45, "pricePerSeat": 80.00, "currency": "SAR", "departureTimeUtc": "2026-03-20T06:00:00Z", "arrivalTimeUtc": "2026-03-20T10:30:00Z", "description": "Direct express service with rest stop", "stops": [ { "location": "Bahra", "latitude": 22.8167, "longitude": 39.5833, "stopTimeUtc": "2026-03-20T08:00:00Z", "stopOrder": 1, "description": "15-minute break" } ] }'
Endpoint /api/companies/{companyId}/public-trips
Request Body Assigned driver identifier
Assigned vehicle identifier
Total number of available seats
Price per individual seat
Scheduled departure time in UTC
Expected arrival time in UTC
Includes all the same location parameters as company trip routes (fromCity, toCity, coordinates, addresses).
Response Indicates if public trip was created successfully
Unique public trip identifier
{ "success" : true , "message" : "تم إنشاء الرحلة العامة بنجاح" , "data" : { "tripId" : "pubtrip_xyz789" , "message" : "تم إنشاء الرحلة العامة بنجاح" , "departureTimeUtc" : "2026-03-20T06:00:00Z" , "availableSeats" : 45 , "pricePerSeat" : 80.00 , "currency" : "SAR" } }