Create Booking

Reserve a vehicle for a specific time period. This is the core transaction endpoint that allows clients to book available vehicles from the agency's fleet.

The booking creation process involves several behind-the-scenes operations:

1. Availability Check: Verifies the vehicle is not already booked for the requested period
2. Eligibility Verification: Confirms the user has verified documents and a valid driver's license
3. Payment Authorization: Authorizes (but doesn't capture) the payment amount on the user's card
4. Confirmation: Creates the booking record and sends confirmation notifications

Prerequisites

Before creating a booking, ensure the user has:

• A verified phone number and email address
• An approved driver's license on file
• At least one valid payment method
• No outstanding payments from previous bookings

Endpoint

INFO

POST /api/v1/client/bookings

Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer {token}	Yes
X-Agency-Signature	{signature}	Yes

Request Body

Parameter	Type	Required	Description
vehicle_id	integer	Yes	ID of the vehicle to book
start_date	string	Yes	Start datetime (ISO 8601)
end_date	string	Yes	End datetime (ISO 8601)
pickup_location_id	integer	No	Pickup location ID
dropoff_location_id	integer	No	Dropoff location ID
payment_method_id	integer	Yes	Payment method ID

Example Request

curl -X POST https://api.daakey.com/api/v1/client/bookings \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}" \
  -H "X-Agency-Signature: {signature}" \
  -d '{
    "vehicle_id": 1,
    "start_date": "2024-01-20T10:00:00Z",
    "end_date": "2024-01-20T18:00:00Z",
    "payment_method_id": 1
  }'

Response

Success (201)

{
  "success": true,
  "message": "Booking created successfully",
  "data": {
    "id": 1,
    "status": "upcoming",
    "start_date": "2024-01-20T10:00:00Z",
    "end_date": "2024-01-20T18:00:00Z",
    "vehicle": {
      "id": 1,
      "plate_number": "ABC-123",
      "brand": "Toyota",
      "model": "Corolla",
      "image": "https://api.daakey.com/storage/vehicles/1/thumb.jpg"
    },
    "pickup_location": {
      "id": 1,
      "name": "Downtown Station",
      "address": "123 Main St",
      "latitude": 40.7128,
      "longitude": -74.0060
    },
    "pricing": {
      "duration_hours": 8,
      "hourly_rate": 15.00,
      "subtotal": 64.00,
      "tax": 6.40,
      "total": 70.40,
      "currency": "USD"
    },
    "payment": {
      "method": "Visa •••• 4242",
      "status": "authorized"
    },
    "created_at": "2024-01-15T00:00:00Z"
  },
  "meta": {
    "agency_id": 123,
    "agency_code": "AGENCY123"
  },
  "request_id": "uuid",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Error (422) - Validation

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "vehicle_id": ["The selected vehicle is not available for the requested time."],
    "end_date": ["The end date must be after start date."]
  },
  "data": null,
  "request_id": "uuid",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Error (409) - Conflict

{
  "success": false,
  "message": "Vehicle is not available for the selected dates",
  "data": {
    "conflicting_booking": {
      "start_date": "2024-01-20T08:00:00Z",
      "end_date": "2024-01-20T12:00:00Z"
    }
  },
  "request_id": "uuid",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Notes

• Payment is authorized but not captured until booking starts
• Minimum booking duration is 1 hour
• Maximum booking duration is 30 days
• A valid driver's license is required
• Cancellation policy applies based on agency settings