Overview

The Hotels Async API - extends the functionality of the standard Hotels search by incorporating asynchronous search capabilities.

This allows for the initial search results to be returned within seconds, enabling you to present them to end users almost immediately.

As more results become returned, new hotels returned can be retrieved with a simple "Get Async Results" request, allowing partners to continuously populate additional hotel options without the need to wait to all suppliers responses.

Hotels Async API Flow

Login

The HSP API is a session-based service, so proper session creation and management are crucial.

The "Login" request is optional as it primarily establishes a connection and retrieves the sessionID.
Initiating a "Search Hotels" request will automatically establish the session and the sessionID will be included in the response.

👍

Note

The SessionID can be retained for future use, allowing you to revisit and analyze the API's requests and responses to & from HSP, to & from the connected suppliers, submit a ticket to the support team referencing the specific session and more.

---

Search Async

The Search Async request allows you to search for Hotels based on :

• Geo Locations (latitude and longitude) with a radius of up to 75 km.
• HotelID/s (up to 3,000 hotel IDs in a single request).

👍

The first response is returned as defined in the 'AwaitTimeForInitialResultsSeconds' field, while the search continues to aggregate additional results in the background according to the 'TimeoutSeconds' field.

👍

NOTE:

Before initiating a Search Hotels request, please select your preferred Detail Level, which determines the data fields returned in the response.

---

Get Async Results

The Get Async Results call retrieves the updated search response, including all additional properties gathered since the first results were returned.

Once the "IsSearchFinished" field becomes true, it indicates that the search process is complete, and there is no need to call "Get Async Results" again, Hence , the search has reached its conclusion, and the results are final.

👍

Explained:

If the 'Search Async' response is returned after 2 seconds, for example, the search will continue to aggregate additional results in the background.

When you initiate the 'Get Async Results' request, all additional properties gathered after those initial 2 seconds will also be included.

---

Get Packages

GetPackages request is used to get updated room information in a specific a hotel.
In order to send this request, all you need is the hotelID & sessionID which returned in the Search Hotels response.

In order to receive the "Supplier Original Room Name" along with HSP mapped name - please contact our support team for special implementation.

In order to obtain the Supplier Recommended Selling Price (SRSP), please first verify that the supplier offers this feature and ensure it is activated on your account from the supplier's side.

👍

SRSP - Supplier Recommended Selling Price :

The SRSP currency is in "SupplierCurrency" tag and NOT the "Currency" tag.

The SRSP is supported by:

• TotalStay (TTS) .
• HotelBeds (HB2).
• Yalago (YLG).
• WelcomeBeds (WLC) .
• AbreuOnlline (ABR).
• RateHawk (RTH)-"min_price" in the SRSP tag.
• GetARoom (GTR) - "reference-amount" as SRSP.
• BedToYou (SHT) - "minAmount" as SRSP.

---

Get Cancellation Policy

This function sends a request for the cancellation policy and should be used before sending a booking
request.

In order to send this request, all you need is the hotelID , PackageID & sessionID that was returned in the GetPackages response.

👍

NOTE :

When initiating Multi-Cxl-Policy -
this call should be used only once the end-user wants to retrieve information for a specific rate and under no circumstances should be used to retrieve ALL cancellation policies for all package IDs returned.

---

Get Payment Preferences

Payment Preferences is used to retrieve the booking payment possibilities for a selected package.
In order to send this request, all you need is the hotelID , PackageID & sessionID that was returned in the GetPackages response.

Payment preferences will specify if the user (whose credentials were used to access the API and to
create the session) is allowed to make a booking, if he/she can pay by credit card (internal/external),
cash or other alternative method (pay upon arrival).

---

Book Hotel

Submits a new booking request for the selected hotel and returns the booking reference and booking status.
You can book only those items that were returned in the last search, in the same session. The same package can be booked several times, depending on 3rd party supplier restrictions for duplicate bookings. In such case an error will be returned which will prevent further booking attempts of the same package.

The Book response may take up to 180 seconds, as it relies on responses from suppliers and, in certain instances, incorporates SmartBook logic or Dynamic Markups that utilize sophisticated business logic.

🗒️

Custom Fields

When initiating a booking request, please note that there are two optional fields, known as custom fields.

While Gimmonix support these custom fields, it's important to remember that suppliers might not offer this feature. Therefore, the inclusion of these fields in your request will depend on the supplier's ability to support them.

• CustomBookingReference
  This field grants the option to forward a custom booking reference to supplier.
  Supported suppliers :

  
  

  Abbey Tours, Abbey Tours Ireland, AbreuOnline,Accor, AfricaStays, Agoda, Amadeus, AM Resorts, Arabian Adevntures, ATI, Bahia Priciples, BeLive, BestWestern, Bonotel, Booking.com, Destination Italia, Disney, DOTW, EgyptExpress, Escalabeds, Expedia, Excellence, GetARoom, GoGlobal, GRN, GTA, Haven Riviera Cancun, Hilton, HotelBeds, HotelPlanner, HotelHub, HotelTrader, Hotusa, IBS, Jonview, Kaluah Tours, KTSFrance, LCI, LotsOfHotels, Majestic, Marriot, NavH, Ocean, Peak Point Global , PriceTravel, PrimeTravel, Ressolutions, RIU, Rustar, Saltours, Sirenis, Smyrooms, SUN, TBO, Tour D’Afrique, Towers , Travco2, Travellanda, TTHTravel, Valentin Imperial, Vertical Booking, Viva Wyndham, WelcomeBeds, WithinEarth, WorldwideHotelLink, Wyndham, YouTravel

• RoomsRemarks
  This field grants the option to forward a free text custom room remarks to supplier.
  Supported suppliers :

  AcademService, Agoda, Amadeus, AM Resorts, ASALondon, ATI, Amadeus AVH, Avra Tours, Bahia Priciples , BeLive, Bico, B2BTravel, Bonotel, Booking.com, Bronevik, CTrip, Darina, Destination Italia, Dida Travel, EgyptExpress, Escalabeds, Eexpedia ,Excellence, FastPay Hotels Direct, GoGlobal, GRN, GTA, Haven Riviera Cancun, HotelPlanner, HotelHub, Hotusa, HRS, IBS, Imperatours, Jacob, JumboTours,Kaluah Tours, LateRooms, LotsOfHotels, Majestic, MarkInternational, Methabook, Miki, Nuitee, Ocean, Omnibees, OTS, Peak Point Global, PriceTravel, PrimeTravel, RIU, RoomerTravel, RTS, Sabre, Sirenis, SershTourism, STGlobe, SUN, TeamAmerica, TotalStay, Tourico, TourPlan, Towers, Travco2, TravelGuru, Travstore, Valentin Imperial , Veturis, Viva Wyndham, Yalago

---

Post Booking

After successfully booking a hotel using the recommended booking flow, there are further optional requests you can use after the booking made .

Cancel a Segment

This function submits a request to cancel an existing Segment with Status 'OK'.

reservations with multi rooms:
(1) there are suppliers that return a single booking confirmation id for all rooms together - on HSP all rooms will be under single Segment ID.

(2) there are suppliers that return for each room a unique booking confirmation id - on HSP each room will have wis own single Segment ID (correlated with supplier).

'Cancel Book' request supports single Segment ID only.

for case (1): all rooms will be cancelled at once
for case (2): requires to send multi calls for 'Cancel Book' in order to cancel all rooms / Segments,
or can cancel part of the rooms by relevant Segment ID

---

Check Status

This function submits a request to retrieve the updated status and booking data.