Understanding our booking endpoints¶

What does it do?¶

Our booking endpoints provide details about all of your upcoming bookings allowing you to retrieve & manage them. It's important to note that past bookings will only be available for 2 hours after the pickup time has elapsed. There are two endpoints available enabling you to fetch all of your bookings (with filters & pagination) or retrieve a single specific booking.

Why use it?¶

A booking can exist in a number of states within the Booking.com Taxi system. There are various use cases where this information would be useful, for example, if you want to display a list of all your upcoming bookings in your user interface with the option to "drill-down" into a single booking where you might want to show greater detail. Our booking management endpoints also allow you to accept or reject bookings.

How does it work?¶

Our booking management endpoints are part of the Taxi Public API, you'll need to authenticate with the API to get started.

High-level Flow¶

1. Once on-boarded a clientID and clientSecret will be provided to you. The authentication endpoint can be called to exchange the keys with an access token which is then used to authenticate each subsequent request.
2. Once you've retrieved an access token, you can fetch all bookings assigned to you by calling /v1/bookings. The endpoint provides pagination & filters to enable you to retrieve a specific set of bookings.
3. It's possible to also retrieve a specific booking by calling /v1/bookings/:customerReference/:bookingReference, subsequently you can use the state_hash to accept or reject individual bookings via /v1/bookings/:customerReference/:bookingReference/responses. The state_hash field is used to ensure the version of the booking you're attempting to update is the latest. By accepting or rejecting a booking you can transition the booking status.
4. Once the booking has been accepted, driver details need to be assigned. In order to do that, we provide the /v1/bookings/:customerReference/:bookingReference/driver endpoint which accepts the driver details. The endpoint can be called multiple times to change driver details when necessary.

See our endpoint references for more information.

Booking Statuses & Transitions¶

We use a number of book statuses to indicate the current state of the booking, in some cases the booking will require action from the supply partner. Read more information about our booking statuses & transitions.

Pagination¶

When retrieving a large number of bookings the response will be paginated with a default page size of 400. The size of the page can be customised with a query parameter along with the specific page to retrieve and the response will contain links to both the next and previous pages when available. Read more information about how pagination works.

Links¶

We use HATEOS to provide dynamic information in our responses, returned in a links array in responses from the API. The links will enable you to easily navigate the API by providing paths for relevant actions for pagination and accepting or rejecting bookings. The links returned for each endpoint can be viewed in the references.