Asynchronous Search API

The Asynchronous Search API returns results as suppliers respond rather than waiting for all of them to finish. This keeps your UI responsive and makes the search experience feel as fast as your fastest supplier — even when others take longer.

The three-API flow

Search Init — fire and get a token

POST your search criteria. The engine immediately queues requests to all suppliers configured in your channel and returns a search token. This token identifies your search session and is used in every subsequent poll.

POST{baseEndpoint}/api/hotel/availability/init

First poll — get the initial batch

Call the async results endpoint with the token. The first response always returns a maximum of 50 hotels — whichever results are ready soonest. The response also includes an expectedHotelCount so you know how many total results to expect, and a status field.

GET{baseEndpoint}/api/hotel/availability/async/{token}

Keep polling — every 500 ms

Pass the nextResultKey from each response to get the next batch. Continue until the status field returns Completed. At that point all suppliers have responded and no further results are coming — stop polling.

GET{baseEndpoint}/api/hotel/availability/async/{token}?nextResultKey={key}

Status values

InProgress

More results are still being processed. Keep polling. Render whatever hotels you have received so far.

Completed

All suppliers have responded. This is the full result set. Stop polling — no new results will arrive after this status.

Handling rate updates — isNewHotel flag

A supplier that responds later might return the same hotel at a better rate than an earlier supplier already returned. When this happens, the result will include isNewHotel: true.

Replace, don't append. When you receive a result with isNewHotel: true for a hotel already in your displayed list, replace the existing entry with the new one — it has a better rate. If isNewHotel is false, the hotel is already shown and has not improved.

Token behaviour

Token is valid for 1 hour. The search criteria are stored against the token, so downstream APIs (Rooms & Rates, Price, Book) can reference the same search context without you re-sending check-in/check-out and occupancy details each time. If the user starts a new search, a new token is issued.

Do not poll faster than 500 ms. The recommended polling interval is 500 ms. Polling more frequently does not return results faster — suppliers respond on their own schedule — and it creates unnecessary load on both sides.