Karhoo for Developers | Mobility Exchange API and SDK reference

Book a trip

  1. Prerequisites
  2. Get quotes
  3. Book a trip
  4. Trip updates
  5. Trip completion

With a quote selected, the next step is to confirm booking of that quote with the supplying fleet.

Book a trip

A booking for the selected quote is made using the Bookings API

  1. Make a POST request to the /bookings endpoint, sending a valid quote id. Some additional details such as the main passenger’s name and a phone number are required. See the API reference for details and examples.

Note: If you attempt to book a trip using an expired Quote ID the bookings endpoint will respond with a HTTP Status Code of 400 and the error message of "Could not book trip (attempt to book an expired quote)". If this happens, a fresh quote must be requested as in the prior step.

  1. After a request, you can monitor the progress of the booking by calling the /bookings/{id}. If you are only interested in the status of the booking you can also call /bookings/{id}/status.

The status of the Booking Request will be one of the following:

Booking status

Description

REQUESTED

The request is matching to the most efficient available driver (By Dispatch).

CONFIRMED

The request has been accepted by Dispatch.

DRIVER_EN_ROUTE

A driver is “en route” to the start location. This state can occur multiple times in case of a driver re-assignment.

ARRIVED

The driver has arrived. This state might be skipped in some cases.

POB

Passenger is in the vehicle and the ride has “started”.

COMPLETED

Passenger has reached their destination.

NO_DRIVERS_AVAILABLE

The request was unfulfilled because no driver was available.

DRIVER_CANCELLED

The request has been cancelled by Dispatch or driver.

BOOKER_CANCELLED

The request has been cancelled by the rider.

KARHOO_CANCELLED

The request has been cancelled by Karhoo.

FAILED

There was an internal error with the booking.

Related tasks

As part of the trip booking process, the user might need to complete additional, related tasks.

Payment details

Before booking a journey, users typically need to provide payment details. Many of Karhoo's Demand Partners have their own payment solutions and therefore integrate their own payment flow into the application. Details on settling payments with Karhoo and information about Karhoo's Payment API are available when onboarding to the Karhoo Production environment. Please reach out to the Karhoo team for details.

Following a booking

The Follow a Booking endpoint returns booking information for the passenger to access without a need to log in. This can be useful for giving passengers information on future trips.

Search booking history

The Search Booking History API allows for giving end users the ability to review prior trips taken.

See the Bookings API reference for more endpoints and possibilities to create a rich end user booking experience.

Reference

Service

API reference

Errors reference

Bookings

Bookings

Bookings Errors

Troubleshooting

Some potential errors you might encounter are:

Error

Solution

Invalid request payload

Check the request body for invalid parameter names or values.

Could not book trip (attempt to book an expired quote)

Requote the trip.

Updated about a month ago


What's Next

Trip updates

Book a trip


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.