Table of Contents

Search Booking Hotel API Documentation

Overview

This API allows users to search for and retrieve a list of their hotel bookings. It supports pagination to handle a large number of bookings. The search can be filtered by various criteria (though the sample request only shows pagination, other filters might be supported by the API but not documented here).

API Endpoint

  • URL: {{host}}/hub/hotel/booking/search
  • Method: POST
  • Content-Type: application/json

Headers

Key Value Description
Content-Type application/json Response format
Authorization Bearer {token} access token

Request Body

{
  "pageIndex": 0,
  "pageSize": 20
}

Request Field Description

Field Type Required Example Description
pageIndex integer ✅ 0 The 0-based index of the page to retrieve. For the first page, use 0.
pageSize integer ✅ 20 The number of booking records to return per page. For example, 20.

Sample Request

curl --location '{{host}}/hub/hotel/booking/search' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
    "pageIndex":0,
    "pageSize": 20
}'

Sample Response

{
  "durationInMilisecond": 187,
  "totalCount": 121,
  "totalPage": 7,
  "pageSize": 20,
  "pageIndex": 0,
  "clientOverride": false,
  "data": [
    {
      "id": "5c217387-8616-47f7-8f0d-fb12860b5f50",
      "readableId": "KS300525B001",
      "orderBaseInfo": {
        "providerCode": "hotel.provider1",
        "status": "PENDING",
        "statusIsFinal": false,
        "bookingType": "hotel",
        "totalAmount": 198786000.0,
        "totalAmountUSD": 0.0,
        "totalAmountVND": 0.0,
        "currency": "VND",
        "convertionRate": 0.0,
        "isNeedRebookPNR": false,
        "passengerCount": 0,
        "totalAmountAtHotel": 0.0,
        "payAtHotelCurrency": "",
        "refunded": false,
        "lastTicketTime": "2025-05-30T08:27:40.3786305Z"
      },
      "orderHotelInfo": {
        "id": "10602dcc-779a-4f4f-8368-3223e5a50d63",
        "hotelBookingId": "5c217387-8616-47f7-8f0d-fb12860b5f50",
        "providerCode": "hotel.provider1",
        "providerReferenceId": "12622279",
        "hotelName": "Sherwood Residence",
        "vatIncluded": false,
        "hasBreakfast": true,
        "extraBed": false,
        "nonSmoking": true,
        "rooms": [
          {
            "id": "00531673-0d50-419f-a494-2b8131a4e42f",
            "providerCode": "hotel.provider1",
            "providerReferenceId": "12622279-201309111",
            "roomName": "3 Bedroom Premier with Balcony",
            "guestIndex": 1,
            "firstName": "Thế CTO",
            "lastName": "Võ",
            "phoneNumber": "987646747",
            "email": "the.vo@tripdata.vn",
            "bedOption": {
              "id": "b1eb0555-207b-4c81-afca-c91de13e7a4c",
              "name": "1 giường cỡ king và 2 giường đơn",
              "quantity": 3
            }
          },
          {
            "id": "4cf33694-f31e-46e0-830b-7eb9130c0fd7",
            "providerCode": "hotel.provider1",
            "providerReferenceId": "12622279-201309111",
            "roomName": "3 Bedroom Premier with Balcony",
            "guestIndex": 2,
            "firstName": "Thành Dev4",
            "lastName": "Nguyễn",
            "email": "thanh.nguyen@tripdata.vn",
            "bedOption": {
              "id": "c04e6125-fbd8-4fe2-ad28-7c908fa5b58e",
              "name": "1 giường cỡ king và 2 giường đơn",
              "quantity": 3
            }
          },
          {
            "id": "3ee10343-9c75-4763-ad21-6fe2dba72ae2",
            "providerCode": "hotel.provider1",
            "providerReferenceId": "12622279-201309111",
            "roomName": "3 Bedroom Premier with Balcony",
            "guestIndex": 3,
            "firstName": "Thế CTO",
            "lastName": "Võ",
            "phoneNumber": "987646747",
            "email": "the.vo@tripdata.vn",
            "bedOption": {
              "id": "6bcf04b1-8104-44c2-811b-a377a290f830",
              "name": "1 giường cỡ king và 2 giường đơn",
              "quantity": 3
            }
          }
        ]
      },
      "orderHotelContactInfo": {
        "email": "the.vo@tripdata.vn"
      },
      "createdBy": "thanh.nguyen2@tripdata.vn",
      "agentId": "NV9999",
      "createdUtc": "2025-05-30T08:12:40:6966",
      "updatedBy": "694E6C9E-ED3C-43EB-A50F-389ADE398E85",
      "updatedUtc": "2025-05-30T08:27:40:6785"
    }
  ]
}

Response Field Description

The top-level response object contains the following fields:

Field Type Example Description
durationInMilisecond integer 187 The time taken by the server to process the search request, in milliseconds.
totalCount integer 121 The total number of booking records matching the search criteria across all pages.
totalPage integer 7 The total number of pages available for the given pageSize and totalCount.
pageSize integer 20 The number of booking records returned per page (matches the request).
pageIndex integer 0 The 0-based index of the current page (matches the request).
clientOverride boolean false A flag indicating if any client-side override was applied (details would depend on system logic).
data array of objects [...] (see bookingRecord object below) An array containing the booking records for the current page. Each object represents a single booking.

data[] (Booking Record) Object

Each object in the data array represents a booking and has the following structure:

Field Type Example Description
id string "5c217387-8616-47f7-8f0d-fb12860b5f50" The unique identifier for the booking/order.
readableId string "KS300525B001" A human-readable identifier for the booking.
orderBaseInfo object (see orderBaseInfo object below) General information about the order.
orderHotelInfo object (see orderHotelInfo object below) Detailed information specific to the hotel booking.
orderHotelContactInfo object (see orderHotelContactInfo object below) Contact information for the hotel booking.
createdBy string "thanh.nguyen2@tripdata.vn" Identifier (e.g., email) of the user/system that created the booking.
agentId string "NV9999" Identifier of the agent, if the booking was made by an agent.
createdUtc string "2025-05-30T08:12:40:6966" ISO 8601 datetime string of when the booking was created.
updatedBy string "694E6C9E-ED3C-43EB-A50F-389ADE398E85" Identifier of the user/system that last updated the booking.
updatedUtc string "2025-05-30T08:27:40:6785" ISO 8601 datetime string of the last update to the booking.

orderBaseInfo Object

Field Type Example Description
providerCode string "hotel.provider1" The code of the hotel provider.
status string "PENDING" Current status of the booking (e.g., "EXPIRED", "PENDING", "CONFIRMED").
statusIsFinal boolean false Indicates if the current status is the final status of the booking.
bookingType string "hotel" Type of booking (e.g., "hotel").
totalAmount decimal 198786000.0 The grand total amount for the booking in the specified currency.
totalAmountUSD decimal 0.0 Total amount in USD.
totalAmountVND decimal 0.0 Total amount in VND.
currency string "VND" The currency code for totalAmount.
convertionRate decimal 0.0 Conversion rate used.
isNeedRebookPNR boolean false Indicates if PNR rebooking is needed.
passengerCount integer 0 Number of passengers (for flight related bookings).
totalAmountAtHotel decimal 0.0 Amount to be paid at the hotel.
payAtHotelCurrency string "" Currency for hotel payment.
refunded boolean false Indicates if the booking was refunded.
lastTicketTime string "2025-05-30T08:27:40.3786305Z" ISO 8601 datetime string representing a deadline related to the booking (e.g., payment).

orderHotelInfo Object

Field Type Example Description
id string "10602dcc-779a-4f4f-8368-3223e5a50d63" Unique identifier for the hotel-specific part of this booking.
hotelBookingId string "5c217387-8616-47f7-8f0d-fb12860b5f50" References the main booking id.
providerCode string "hotel.provider1" Provider code for the hotel.
providerReferenceId string "12622279" The hotel's unique ID from the provider's system.
hotelName string "Sherwood Residence" Name of the booked hotel.
vatIncluded boolean false Indicates if VAT is included.
hasBreakfast boolean true Indicates if breakfast is included.
extraBed boolean false Indicates if an extra bed is included.
nonSmoking boolean true Indicates if the booked room is non-smoking.
rooms array of objects [...] (see orderHotelInfo.room object below) Details of each room booked (summary, lead guest info per room).

orderHotelInfo.rooms[] (Booked Room Summary) Object

Field Type Example Description
id string "00531673-0d50-419f-a494-2b8131a4e42f" Unique identifier for this booked room instance.
providerCode string "hotel.provider1" Provider code for this room.
providerReferenceId string "12622279-201309111" The room type's ID from the provider.
roomName string "3 Bedroom Premier with Balcony" Name of the booked room type.
guestIndex integer 1 Index indicating which guest (from original booking) is associated with this room.
firstName string "Thế CTO" First name of the lead guest for this room.
lastName string "Võ" Last name of the lead guest for this room.
phoneNumber string "987646747" Phone number of the lead guest for this room (if available).
email string "the.vo@tripdata.vn" Email of the lead guest for this room.
bedOption object (see bedOption object below) Details of the bed option selected for this room.

orderHotelInfo.rooms[].bedOption Object

Field Type Example Description
id string "b1eb0555-207b-4c81-afca-c91de13e7a4c" Unique identifier for this booked bed option instance.
name string "1 giường cỡ king và 2 giường đơn" Description of the bed option.
quantity integer 3 Quantity related to the bed option.

orderHotelContactInfo Object

Field Type Example Description
email string "the.vo@tripdata.vn" Primary contact email for the booking.

Notes

  • This API is used to retrieve a paginated list of existing hotel bookings.
  • The pageIndex and pageSize parameters are mandatory for pagination.
  • The response includes pagination metadata (totalCount, totalPage, etc.) to help navigate through the booking records.
  • Each item in the data array represents a booking and contains a summary of the booking details. For full booking details, you might need to use a "Get Booking Details" API using the id.
  • The structure of orderHotelInfo.rooms in this search response is a summarized version, primarily showing lead guest information per room, compared to the more detailed guest list in the "Book Hotel API" response.
  • Additional request parameters for filtering (e.g., by date, status, booking ID) might be supported by the API but are not detailed in the provided sample. Check with the API provider for a full list of supported filters.