Fleet Management API​

We're excited to introduce the Fleet Management API, a comprehensive solution for managing your transportation fleet operations. This new API enables you to build fleet management dashboards, automate operations, and integrate with your existing systems.

API Base URLs​

• Sandbox: https://api.sandbox.goodjourney.io/api/management
• Production: https://api.goodjourney.io/api/management

Key Features​

The Fleet Management API provides comprehensive endpoints for managing all aspects of your fleet:

Driver Management​

• Create, update, and manage driver accounts
• Assign vehicles to drivers
• Track driver information and credentials

Vehicle Management​

• Manage vehicle inventory and configurations
• Create and update vehicle records
• Manage vehicle types, capacity, and luggage capacity

Supplier Management​

• Manage supplier companies and relationships
• Create and manage supplier user accounts
• Configure supplier operation zones, commission settings, and bank information

Corporate Accounts​

• Manage corporate clients and their settings
• Create and manage corporate user accounts
• Manage corporate travelers and traveler profiles

Zone Management​

• Configure operation zones (geographical areas where your fleet operates)
• Manage restricted zones (areas with operation limitations)
• Configure flat-rate zones (areas with fixed pricing)

Rate Management​

• Configure regular point-to-point rates based on distance and time
• Set up flat-rate pricing for specific routes or zones
• Manage hourly rate packages with duration and distance options
• Configure surcharge policies, customer policies, and supplier policies
• Create and assign rate templates

File Upload​

• Upload images and files to cloud storage

Authentication​

All endpoints require authentication using a Bearer token with fleetManager permission. Obtain your access token through the Authentication API.

Documentation​

For detailed API documentation, including all available endpoints, request/response schemas, and examples, please refer to the Fleet Management API specification.

Booker Contact Requirement Update​

You can now create or update passenger information without providing a phone number.

Affected API Endpoints​

• Create booking with quote
• Create custom booking

Description​

Either the booker's phone number or email address is now required when creating a booking.
At least one of these fields must be provided to proceed with the request.

Example Request​

{
  "booker": {
    "title": "Mr",
    "firstName": "David",
    "lastName": "James",
    "email": "passenger@example.com"
  },
  ...
}

1. Passenger Phone Number is Now OptionalAPI Endpoints:​

You can now create or update passenger information without providing a phone number.

Affected API Endpoints​

• Create booking with quote
• Create custom booking
• Update a booking

Example Request​

{
  "passenger": {
    "title": "Mr",
    "firstName": "David",
    "lastName": "James",
    "email": "passenger@example.com"
  },
  ...
}

2. Added groupId field in booking & booking history response​

A new field, groupId, has been added to several booking-related API responses and webhooks.

The following endpoints and webhooks return additional fields in their responses:

API Endpoints:

• Create booking with quote
• Create custom booking
• Get a booking
• Get list bookings
• Get booking history

Webhooks:

• bookingCreated
• bookingStatus

Response Fields​

groupId (String, Optional)​

• Identifier of the booking group
• Example: G1618

Example API Response​

{
  "bookId": "93123613947",
  "groupId": "G1618",
  "status": "accepted",
  "duration": 2,
  "vehicle": {
    "plateNumber": "ABC-1234",
    "make": "Toyota",
    "model": "Camry",
    "color": "Black"
  },
  "flightNumber": "AA5633",
  "corporate": {
    "id": "corp_12345",
    "name": "Acme Corporation"
  },
  "internalComment": "VIP client - priority service",
  "comment": "Please call upon arrival",
  ...
}

Example Booking history Payload​

{
  "bookingId": "93123613947",
  "groupId": "G1618",
  "bookingStatus": "completed",
  "flightNumber": "AA5633",
  "corporateId": "corp_12345",
  "corporateName": "Acme Corporation",
  "internalComment": "VIP client - priority service",
  "notes": "Please call upon arrival",
  ...
}

1. Internal Comment Support in Booking Requests​

Added: internalComment field to booking creation and update requests

The following endpoints now accept an internalComment field in their request payloads:

API Endpoints:

• Create booking with quote
• Create custom booking
• Update a booking

New Request Field​

internalComment (String, Optional) - Request Field​

• Internal notes visible only to dispatchers and operations staff
• Used for internal coordination or operator instructions
• Not visible to drivers or passengers
• Example: "VIP client - priority service"

2. Enhanced Booking History Filters​

Added: New query parameters for the booking history endpoint

The Get booking history endpoint now supports additional filters:

New Query Parameters​

bookId (String, Optional)​

• Filter by booking ID
• Example: 93123613947

bookingReference (String, Optional)​

• Filter by external booking reference
• Example: 62549263846

3. Enhanced Booking Response Fields​

Added: New fields in booking responses to support fleet operations and improve coordination

The following endpoints and webhooks return additional fields in their responses:

API Endpoints:

• Create booking with quote
• Create custom booking
• Get a booking
• Get list bookings
• Get booking history

Webhooks:

• bookingCreated
• bookingStatus
• assignedDriver
• assignedVehicle
• driverLocation

Response Fields​

duration (Integer, Optional)​

• Total trip duration in hours
• Example: 2 (represents 2 hours)
• Available in: booking responses and bookingCreated/bookingStatus webhooks

vehicle (Object, Optional)​

• Vehicle information assigned to the booking
• Only present when a vehicle has been assigned
• Properties:
  • plateNumber (string): Vehicle license plate number
  • make (string): Vehicle manufacturer/brand (e.g., Toyota, Honda)
  • model (string): Vehicle model name (e.g., Camry, Accord)
  • color (string): Vehicle color (e.g., Black, White, Silver)
• Example: {"plateNumber": "ABC-1234", "make": "Toyota", "model": "Camry", "color": "Black"}
• Available in: booking responses and webhooks

flightNumber (String, Optional)​

• Passenger's flight number, if applicable
• Useful for airport pickup coordination and flight tracking
• Example: "AA5633"

corporate (Object, Optional)​

• Corporate account information
• If empty, the booking is considered an individual booking
• Properties:
  • id (string): Corporate account ID
  • name (string): Corporate account name
• Example: {"id": "corp_12345", "name": "Acme Corporation"}

Note: In booking history payloads, these fields are provided as separate fields:

• corporateId (string): Corporate account ID
• corporateName (string): Corporate account name

internalComment (String, Optional) - Response Field​

• Internal notes visible only to dispatchers and operations staff
• Used for internal coordination or operator instructions
• Not visible to drivers or passengers
• Example: "VIP client - priority service"

comment / notes (String, Optional)​

• Updated description: Driver note
• Additional notes or instructions visible to both the driver and passenger
• Examples: passenger preferences, pickup details, or contact instructions
• In API responses: comment field
• In booking history payloads: notes field
• Example: "Please call upon arrival"

Example API Response​

{
  "bookId": "93123613947",
  "status": "accepted",
  "duration": 2,
  "vehicle": {
    "plateNumber": "ABC-1234",
    "make": "Toyota",
    "model": "Camry",
    "color": "Black"
  },
  "flightNumber": "AA5633",
  "corporate": {
    "id": "corp_12345",
    "name": "Acme Corporation"
  },
  "internalComment": "VIP client - priority service",
  "comment": "Please call upon arrival",
  ...
}

Example Booking history Payload​

{
  "bookingId": "93123613947",
  "bookingStatus": "completed",
  "flightNumber": "AA5633",
  "corporateId": "corp_12345",
  "corporateName": "Acme Corporation",
  "internalComment": "VIP client - priority service",
  "notes": "Please call upon arrival",
  ...
}

4. New Webhook Event: assignedVehicle​

Added: New webhook event to notify partners when a vehicle is assigned to a booking

Event Details​

Event Name: assignedVehicle

When Triggered:

• When an operator assigns a vehicle to a booking in Command Center
• When a driver switches to a different vehicle for a booking
• When a vehicle is changed for any booking (even if the driver remains the same)

Webhook Payload:

{
  "bookId": "93123613947",
  "bookingReference": "62549263846",
  "vehicle": {
    "plateNumber": "ABC-1234",
    "make": "Toyota",
    "model": "Camry",
    "color": "Black"
  }
}

Subscribing to the Event:

To receive assignedVehicle webhooks, include it in the events array when subscribing:

POST /api/demand/v1/subscribe
Content-Type: application/json

{
  "url": "https://your-domain.com/webhooks/qup",
  "signingSecret": "your-secret-key-min-30-chars-long",
  "events": [
    "bookingCreated",
    "assignedDriver",
    "assignedVehicle",
    "bookingStatus",
    "driverLocation"
  ]
}

Important Notes:

• The assignedVehicle webhook fires independently from assignedDriver
• A booking may receive both webhooks if both driver and vehicle are assigned simultaneously
• If vehicle information is not available, the webhook will not fire
• Vehicle changes (swapping vehicles) will trigger a new assignedVehicle webhook

📋 Migration Notes​

Backward Compatibility: ✅ All changes are backward compatible

Request Fields:

• New optional internalComment field added to booking creation and update requests
• This field is optional and does not affect existing integrations

Response Fields:

• New optional fields added to booking responses: duration, vehicle, flightNumber, corporate, internalComment
• All new fields are optional and will be included when data is available
• The vehicle field is only present when a vehicle has been assigned to the booking
• No changes required to existing integrations
• Response parsing remains backward compatible

Webhook Events:

• New optional webhook event: assignedVehicle
• This is an opt-in feature; not subscribing to this event has no impact on existing functionality
• Subscribe only if you need real-time vehicle assignment notifications

Query Parameters:

• New optional query parameters added to booking history endpoint: bookId, bookingReference
• These filters are optional and existing queries will continue to work without modification

Hourly Package Selection Logic​

Changed: Package duration filter logic for hourly bookings

• Previous behavior: Selected packages with duration >= requested duration
• New behavior: Selects packages with duration <= requested duration
• Impact: More intuitive package selection - shows packages that fit within requested time
• Example:
  • Before: 5-hour request → returns 5h, 6h, 8h, 10h packages
  • After: 5-hour request → returns 1h, 2h, 3h, 5h packages

Update Booking API​

Enhanced: The Update Booking API now supports additional parameters and flexible datetime formats

New Optional Parameters​

luggage (Integer, Optional)​

• Updates luggage count
• No fare recalculation

passengers (Integer, Optional)​

• Updates passenger count
• No fare recalculation

pickup (Object, Optional)​

• Updates pickup location
• Required fields: latitude, longitude
• Optional fields: address, city, country, postcode
• No fare recalculation

destination (Object, Optional)​

• Updates destination location
• Required fields: latitude, longitude
• Optional fields: address, city, country, postcode
• No fare recalculation

Flexible Pickup DateTime Format​

The pickupDateTime parameter now accepts multiple formats for easier integration:

• Simple format: "2024-10-17 14:30" (YYYY-MM-DD HH:mm)
• With timezone: "2024-10-17T14:30:00.000+07:00"
• UTC format: "2024-10-17T07:30:00.000Z" (still supported)

Example​

PATCH /api/demand/v1/bookings/:bookId
{
  "pickupDateTime": "2024-10-17 14:30",
  "luggage": 3,
  "passengers": 4,
  "pickup": {
    "latitude": 13.7563,
    "longitude": 100.5018,
    "address": "New Address"
  }
}

📋 Migration Notes​

Backward Compatibility: ✅ All changes are backward compatible

1. Hourly Package Logic:

   • Existing bookings are not affected
   • Only new quote and booking requests are affected
   • No integration changes required

2. Update Booking API:

   • All new parameters (luggage, passengers, pickup, destination) are optional
   • Multiple datetime formats supported: YYYY-MM-DD HH:mm, ISO 8601 with timezone, or UTC
   • Existing update calls work without any changes
   • You can adopt new parameters and formats when needed
   • All formats are supported indefinitely

• Multiple Bookings Support

  • Added vehicleIdentifier parameter to support multiple bookings with the same external booking reference
  • Allows creating multiple vehicle bookings for a single booking reference by providing different vehicleIdentifier values
  • Duplicate prevention: System rejects bookings with the same combination of bookingReference and vehicleIdentifier

• Enhanced Booking Filtering

  • Added bookingReference query parameter to GET /v1/bookings endpoint
  • Enables filtering and retrieving all bookings associated with a single external reference
  • Use case: Query all vehicles for a booking when using multiple vehicleIdentifier values

• Booking Activities API

  • Added new endpoint: POST /v1/bookings/{bookId}/activities to create booking activities
  • Added new endpoint: GET /v1/bookings/{bookId}/activities to retrieve booking activities
  • Activities support role-based visibility permissions (operator, driver, passenger)
  • Default permissions: visible to all roles unless specified otherwise

Enhanced​

• Create booking with quote

  • Added optional vehicleIdentifier parameter (integer)
  • Description: "Optional number to identify multiple vehicles for the same booking reference"

• Create custom booking

  • Added optional vehicleIdentifier parameter (integer)
  • Description: "Optional number to identify multiple vehicles for the same booking reference"

• Get a booking

  • Response now includes vehicleIdentifier field
  • Returns the vehicle identifier if set during booking creation

• Get list bookings

  • Added bookingReference query parameter for filtering
  • Response includes vehicleIdentifier field for each booking

New Schemas​

• CreateBookingActivityRequest

  • content (required): Activity content/note
  • permission (optional): Visibility permissions object
    • operator (boolean, default: true)
    • driver (boolean, default: true)
    • passenger (boolean, default: true)

• BookingActivity

  • id: Activity ID
  • bookId: Booking ID
  • content: Activity content
  • createdDate: Activity creation timestamp
  • permission: Visibility permissions object

• BookingActivityResponse

  • success: Boolean indicating operation success
  • activity: BookingActivity object

• BookingActivitiesListResponse

  • bookId: Booking ID
  • activities: Array of BookingActivity objects
  • total: Total number of activities

• New Booker Schema

  • Added booker schema with fields: title, firstName, lastName, phone, and email

  • {
      title: String,
      firstName: String,
      lastName: String,
      phone: String,
      email: String
    }
    
  • Passenger information can be omitted when booker information is provided

• Hourly Package Support

  • Added packageId field for hourly package identification
  • Added packageDuration field for hourly package duration in hours

• Enhanced Booking Requirements

  • Added conditional validation for destination and duration fields
    • destination is required when duration is not provided
    • duration is required when destination is not provided
  • Added conditional validation for booker and passenger fields
    • booker is required when passenger is not provided
    • passenger is required when booker is not provided

• Duration

  • Added new duration field for specifying trip duration in hours
  • Added minimum value of 1 hour for duration fields

Enhanced​

• Get quotes

  • Added conditional validation for destination/duration requirements
  • Added conditional validation for booker/passenger requirements
  • Enhanced field descriptions with clear conditional logic

• Create custom booking

  • Added conditional validation for destination/duration requirements
  • Added conditional validation for booker/passenger requirements

• Create booking with quote

  • Added conditional validation for booker/passenger requirements

• Booking Response

  • Added booker field to booking response
  • Added bookerPhone and bookerName fields to booking history response

Technical Improvements​

• Improved API schema validation with conditional requirements
• Added proper validation constraints for duration fields

• Update a booking adjustments

  • Support update adjustments on a completed booking

• Get quotes

  • Support on-demand booking by allow input string ASAP as the pickupDateTime

    • Example

      {
        ...
        pickupDateTime: "ASAP"
      }
      

  • For on-demand bookings, added new key eta in the response data to provide the estimated distance & duration from the nearest driver to the pickup point

    • Example

      {
        ...
        eta: {
          distance: 6345,
          duration: 343
        }
      }
      

• Create custom booking

  • Support on-demand booking by allow input string ASAP as the pickupDateTime

• User permission: Added role for user.

  • partner
  • fleetManager

• Booking

  • Added source field to booking
  • Added email field to passenger object
  • Validate passenger's phone in E.164 format

• Webhooks

  • Added new webhook bookingCreated for fleetManager user.
  • New endpoints for fleetManager
    • Subscribe a webhook
    • Unsubscribe a webhook
    • Get list subscribed webhooks

• New endpoints for creating custom booking: Added 2 new endpoints for fleetManager to create custom booking

  • Get list vehicle types
  • Request new custom booking

Updated​

• Create booking with quote
  • Made pickupTimezone parameter optional. If pickupTimezone is not included we will base the timezone on the pickup location.