Integration Guide

Account Structure Client → Account IDs → Providers → Channels

A client can have multiple account IDs (sandbox and live). Each account has providers — your individual supplier contracts configured by ZentrumHub — and channels, which are logical groupings of those providers with their own business rules.

A channel is your line of business. You pass a channelId in every API call to tell the engine which suppliers to use and which markup and discount rules to apply. One provider can belong to multiple channels; one channel can have one or many providers. Examples: a geography-based channel that only calls suppliers with strong European inventory, or a premium channel that applies higher markups for VIP customers.

Search Types How the engine knows where to look

Every search needs coordinates, not just a destination name. That is why Autosuggest exists — it maps text input to precise location data that drives the search.

Circular — a centre lat/long plus a radius in kilometres. Use for hotel or point-of-interest searches where you want results within a tight area.
Polygon — the full boundary of a city as a coordinate set. More precise than circular because it respects actual city limits.
Multi-polygon — like polygon, but for fragmented areas where parts of a city or region are geographically separated.
Hotel ID — bypass location entirely and fetch a specific hotel directly. Used for hotel detail pages and promotions.

Rule of thumb: if Autosuggest returns type city, use polygon. If it returns hotel or pointOfInterest, use circular with a 2–5 km radius.

Search Mode Asynchronous vs Blocking

Asynchronous (recommended) — fire the search, receive a token immediately, then poll every 500 ms. Results stream in as suppliers respond. The token stays valid for one hour. Status will be InProgress until all suppliers have responded, then Completed — stop polling at that point. The first response is capped at 50 hotels so something renders on screen quickly; subsequent polls return the next batch.

Blocking — the API waits for all configured suppliers to respond before returning anything. Simpler to implement but slower. Appropriate when wait time is not a concern.

Rooms & Rates Five objects, one response

The Rooms & Rates API is the most complex in the engine. Here is what each object means:

Rooms — raw room data from all configured suppliers. If 5 suppliers return the same king room, you will see it 5 times here.
Rates — raw rate data across all suppliers. In multi-room searches a single recommendation can have multiple rate IDs, because some suppliers bundle all rooms into one rate while others give a separate rate per room. Always check occupancies to confirm how many rooms a rate covers.
Recommendations — ZentrumHub's deduped unique rate plans. One recommendation equals the cheapest rate for a specific combination of room type, board basis, and refundability across all suppliers. This is the engine's core business logic.
Standardised Rooms — mapping-service-normalised unique rooms. From 50 raw rooms across 10 suppliers you get the actual 5 unique rooms. Mapping service integration is mandatory for multi-supplier setups.
Standardised Room Groups (recommended) — the developer-friendly object that combines standardised rooms with their available rate plan options and a pre-calculated total. Sorted cheapest to highest. Use this as your primary implementation path — it removes the need to manually cross-reference recommendations against rooms.