POC: Hotels API

Hotels API

Step 1: Preparation

In order to test our Hotels API, HSP suggest a recommended flow when searching and bookings hotels.
Using the recommended booking flow will decrease potential errors and increase your productivity.

When it comes to preparing the API requests, headers along with the respective endpoints, we have dedicated a fully and easy to understand Documentation for our Hotels API, along with explanations and ready to test postman collection.

For our Hotels API Documentation and Postman Collection - Click here.

If you can check all the prerequisites here - please proceed to Step 2.

  • I've obtained a test credentials (Username and Password).
  • I've understood the minimal and recommended Hotels flow.
  • I've set the environment to test the API.

Step 2: Integrate the API

Once everything is set, we can proceed with testing the API. This can be accomplished in two ways: by initiating either a Login request and creating a new session or by triggering a Search Hotels request using the provided credentials. Please rest assured, we will walk you through the necessary steps.

For ease of understanding - please refer to our Postman API Collection.

1. Search Hotels by Geocodes: The Search Hotels request is designed for searching hotels.

In this request, you must specify all the mandatory fields, which include Geocodes, Radius of the search, check-in and check-out dates, and the number of guests. This will yield a list of hotels within the specified location, along with essential information such as the hotel's name, location, star rating, and an image of the hotel.

2. Get Packages: The Get Packages request requires two important fields: HotelID, which serves as the hotel's identifier returned in the Search Hotels response, and SessionID, which is also provided in the previous response.

This request will provide you with all the available room options within a specific hotel, along with additional details such as cancellation policies, refundability, room content (images, descriptions, and amenities), and more.

3. Get Cxl Policy: The Cancellation Policy request is primarily used to retrieve the cancellation policies for packages, including any applicable penalties and deadlines. This information is extracted from the Get Packages Response.

4. Get Payment Preferences: Payment Preferences is used to retrieve the booking payment possibilities for a selected package. All you need is the HotelID , PackageID & sessionID that was returned in the GetPackages response.

5. Book: The Book request initiates a booking for the selected package and returns the booking status, along with Order/Segment IDs for reference.

Step 3: Asses potential Errors & Use-Cases

Once the API is understood, satisfied and the integration is ready - it is crucial to asses any potential Errors and Use-Cases.


During the search and booking process, several potential errors can arise, and it's essential to anticipate and implement appropriate error handling mechanisms to ensure a smooth and functional session.

Some of the common errors that may occur include:

Wrong Data Entry, Supplier Errors, Communication Errors, Authorization and Authentication Errors, Payment Errors, Availability Errors, Timeouts, Data Validation Errors and more.

It's crucial to have robust error handling in place for each of these scenarios to provide a better user experience and ensure the reliability of your hotel booking system.

More information - Click here.


HSP supports a wide range of use-cases, making it a versatile platform for various hotel booking scenarios. These use-cases include:

Single and Multi-Room Searches, Price Change Handling, Rebooker, Smartbook and much more.

To best serve your customers, it's essential to identify their specific behaviors and needs and then tailor your use-cases and features accordingly. Understanding your clients' requirements will help you create a more user-friendly and efficient hotel booking system that meets their expectations and provides a seamless booking experience.

Step 4: Testing

Once the API integration is completed, and error handling and use-case scenarios are in place, we can proceed with the Proof of Concept (POC) testing. This testing should encompass a comprehensive assessment, including the API flow, user experience, error handling, and performance testing.

This comprehensive evaluation will not only ensure the correct functionality of the API but also assess advanced aspects of your Search and Bookings engine's performance.

Step 5: POC

Once all the steps are completed and you have successfully checked off each item on the POC checklist:

  • Step 1: Preparation
  • Step 2: Integrate the API
  • Step 3: Assess potential Errors & Use-Cases
  • Step 4: Testing

The POC is now fully prepared and ready to proceed with hotel searching and bookings.