Get Room Options

curl "$UNIFYSTAYS_BASE_URL/hotels/123456/rooms" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -d '{
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "language": "en",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ]
  }'

{
  "success": true,
  "message": "Static rooms loaded. Connect to SSE stream for live provider options.",
  "data": {
    "hotel_id": "1393631",
    "hotel_name": "Taj Palace, New Delhi",
    "check_in": "2026-10-20",
    "check_out": "2026-10-21",
    "nights": 1,
    "total_options": 0,
    "providers_queried": ["TRIPJACK", "REZLIVE", "RATEHAWK"],
    "unifystays_rooms": [
      {
        "unifystays_room_id": "4120552",
        "name": "Deluxe Room",
        "details": {
          "source": "TRIPJACK",
          "images": [
            { "url": "https://cdn.example/tj-twin-1.jpg", "caption": null, "is_primary": true }
          ],
          "size": { "value": 32, "unit": "sqm" },
          "description": "Room overlooking the Diplomatic Enclave.",
          "description_format": "TEXT",
          "amenities": [{ "id": "wifi", "name": "Free WiFi" }]
        },
        "suppliers": ["RATEHAWK", "REZLIVE", "TRIPJACK"],
        "variants": [
          {
            "unifystays_room_id": "4120553",
            "beds": [{ "type": "TWIN", "count": 2 }],
            "bedrooms": null,
            "max_guests": 2,
            "smoking": null,
            "suppliers": ["TRIPJACK"]
          }
        ],
        "bed_assignment": { "suppliers": ["REZLIVE"] }
      }
    ],
    "stream_id": "stream_a71c0e9b2f44",
    "sse_stream_url": "/hotels/1393631/rooms/stream/stream_a71c0e9b2f44",
    "options": []
  }
}

POST

hotels

{hotel_id}

rooms

curl "$UNIFYSTAYS_BASE_URL/hotels/123456/rooms" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -d '{
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "language": "en",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ]
  }'

{
  "success": true,
  "message": "Static rooms loaded. Connect to SSE stream for live provider options.",
  "data": {
    "hotel_id": "1393631",
    "hotel_name": "Taj Palace, New Delhi",
    "check_in": "2026-10-20",
    "check_out": "2026-10-21",
    "nights": 1,
    "total_options": 0,
    "providers_queried": ["TRIPJACK", "REZLIVE", "RATEHAWK"],
    "unifystays_rooms": [
      {
        "unifystays_room_id": "4120552",
        "name": "Deluxe Room",
        "details": {
          "source": "TRIPJACK",
          "images": [
            { "url": "https://cdn.example/tj-twin-1.jpg", "caption": null, "is_primary": true }
          ],
          "size": { "value": 32, "unit": "sqm" },
          "description": "Room overlooking the Diplomatic Enclave.",
          "description_format": "TEXT",
          "amenities": [{ "id": "wifi", "name": "Free WiFi" }]
        },
        "suppliers": ["RATEHAWK", "REZLIVE", "TRIPJACK"],
        "variants": [
          {
            "unifystays_room_id": "4120553",
            "beds": [{ "type": "TWIN", "count": 2 }],
            "bedrooms": null,
            "max_guests": 2,
            "smoking": null,
            "suppliers": ["TRIPJACK"]
          }
        ],
        "bed_assignment": { "suppliers": ["REZLIVE"] }
      }
    ],
    "stream_id": "stream_a71c0e9b2f44",
    "sse_stream_url": "/hotels/1393631/rooms/stream/stream_a71c0e9b2f44",
    "options": []
  }
}

Call this endpoint after the customer selects a hotel. It is the second step of the flow: Search → Rooms → Prebook → Book. Send the same dates, occupancy and nationality used for hotel search. Unifystays calls the active suppliers in parallel and normalizes their room options. The POST returns quickly. It answers with the rooms Unifystays already knows for this hotel and a stream_id / sse_stream_url. The live supplier offers then arrive on that stream as Server-Sent Events, one provider_options event per supplier batch, and a final done event. Read the stream with Stream Room Updates. Each streamed offer carries two identifiers you need later:

booking_token: identifies the whole offer. You send it to Prebook.
room_allocation_id: identifies one room slot of the offer.

POST the stay

Send dates, nationality and the occupancy of every room. Keep data.unifystays_rooms and open data.sse_stream_url immediately.

Read the stream

Add family objects and offers as provider_options events arrive. Stop at done.

Show room cards

Draw one card per room family with the offers under it (see Render Room Cards).

Prebook the chosen offer

Send its booking_token unchanged to Prebook.

Request Example

curl "$UNIFYSTAYS_BASE_URL/hotels/123456/rooms" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -d '{
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "language": "en",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ]
  }'

Request Fields

Field	Where to get it	How it is used
Path `hotel_id`	`hotel_id` from the selected hotel-search or autocomplete result	Selects the hotel whose live room inventory is requested.
`check_in`, `check_out`	Your customer’s stay form	Must describe the same stay the customer selected during search.
`nationality`	`iso_code` from Nationalities	Used by suppliers for market eligibility, pricing, and booking rules. Defaults to `residency` when omitted.
`residency`	Your guest form (ISO 3166-1 alpha-2)	Optional. Used for residency-restricted rates. Defaults to `nationality`. When both are omitted `IN` is used, so always send at least one.
`language`	Your locale (for example `en`)	Optional. Echoed in `quote_context.language` of each offer.
`rooms`	Your occupancy form	Send 1–8 entries, one for every room the customer needs. Array position is preserved as a room allocation.
`rooms[].adults`	Your occupancy form	Number of adults staying in that room (1–5). Adults plus children must not exceed 5 per room.
`rooms[].child_ages`	Your occupancy form	Age of every child staying in that room. Use `[]` when there are no children.

Optional header X-Unifystays-Currency (an ISO 4217 code such as EUR) sets the display currency for this request. Without it the response uses your organization’s display currency, which is USD unless configured. See Display currency. If the customer changes the hotel, dates, nationality, number of rooms, or any room’s occupancy, request room options again. Tokens from the old request must not be reused. Errors: 400 for an invalid body (for example check_in in the past, or check_out not after check_in), 404 when the hotel does not exist. The body is checked when you POST; supplier problems are reported later on the stream, not as an HTTP error.

Initial Response Example

The POST response is intentionally fast. data.options is initially empty; connect to data.sse_stream_url to receive live provider_options events. This example is for a hotel that was searched before. On a hotel’s first search unifystays_rooms is [].

{
  "success": true,
  "message": "Static rooms loaded. Connect to SSE stream for live provider options.",
  "data": {
    "hotel_id": "1393631",
    "hotel_name": "Taj Palace, New Delhi",
    "check_in": "2026-10-20",
    "check_out": "2026-10-21",
    "nights": 1,
    "total_options": 0,
    "providers_queried": ["TRIPJACK", "REZLIVE", "RATEHAWK"],
    "unifystays_rooms": [
      {
        "unifystays_room_id": "4120552",
        "name": "Deluxe Room",
        "details": {
          "source": "TRIPJACK",
          "images": [
            { "url": "https://cdn.example/tj-twin-1.jpg", "caption": null, "is_primary": true }
          ],
          "size": { "value": 32, "unit": "sqm" },
          "description": "Room overlooking the Diplomatic Enclave.",
          "description_format": "TEXT",
          "amenities": [{ "id": "wifi", "name": "Free WiFi" }]
        },
        "suppliers": ["RATEHAWK", "REZLIVE", "TRIPJACK"],
        "variants": [
          {
            "unifystays_room_id": "4120553",
            "beds": [{ "type": "TWIN", "count": 2 }],
            "bedrooms": null,
            "max_guests": 2,
            "smoking": null,
            "suppliers": ["TRIPJACK"]
          }
        ],
        "bed_assignment": { "suppliers": ["REZLIVE"] }
      }
    ],
    "stream_id": "stream_a71c0e9b2f44",
    "sse_stream_url": "/hotels/1393631/rooms/stream/stream_a71c0e9b2f44",
    "options": []
  }
}

Use the Response

The initial response contains the rooms already known for this hotel and a stream_id with sse_stream_url. Live supplier options are delivered progressively through the stream. Every streamed bookable option includes a short signed booking_token required by Prebook a Room.

Response key	What it means	What your integration should do
`data.hotel_id`	The Unifystays hotel represented by this room response	Keep it with the selected option and send it as `hotel_id` to prebook.
`data.unifystays_rooms[]`	The hotel’s family objects; store each family and its variants by id. Empty on a hotel’s first search	Store each room by its id and draw an empty card for it until offers arrive.
`data.options[]`	Reserved response field; always empty in the initial response (`total_options` is 0)	Read live options from `provider_options` SSE events.
`data.providers_queried[]`	Suppliers being queried for this hotel	Informational. A listed supplier can still return nothing; the `done` event reports the outcome.
`stream_id`, `sse_stream_url`	Short-lived SSE stream for progressive supplier results	Connect immediately and collect options until the `done` event.
Stream `provider_options.rooms[]`	The family objects the event’s offers use, new or updated	Add or replace each family by `unifystays_room_id`.
Stream `provider_options.options[]`	Complete supplier offers for all requested room slots	The customer selects one complete option; do not combine rooms from different options.
Stream `options[].booking_token`	Opaque, signed identity for the complete selected option; valid for at most 15 minutes (`lifecycle.expires_at`)	Send it unchanged to prebook. Do not create, parse, or modify it.
Stream `options[].offer_family_id`	Offers whose slots are in the same families in the same order share it; `null` when any slot is a `tmp_` room	Use it as the card key for multi-room searches. Never use it for booking.
Stream `options[].rooms[]`	One entry per requested room instance	Put the offer on the card of its slot’s room; show the slot’s own `provider_room` facts on the offer row.
`room_allocation_id`	Opaque identity for one exact room slot	Keep it associated with that slot. Prebook returns the authoritative copy used for booking.
`unifystays_room_id`	The variant (or family, for a hotel-assigned bed type) this slot belongs to; `unifystays_family_id` names the family	Look the family up in your store. Display identity only.
`provider_room`	The seller’s own room: name, beds, maximum guests and whatever static attributes it sent	Always show its beds and maximum guests on the offer row.
`mapping_status`, `mapping_details`	`MAPPED` when the slot is in a built room, `UNMAPPED` for a `tmp_` room; how the slot was matched	Diagnostics only. They do not determine bookability.
`unifystays_room`	Always `null`	Ignore it. Use `unifystays_room_id`.
`occupancy`	Adults and child ages quoted for this allocation	Keep guest assignment compatible with this occupancy.

Room grouping never changes what is booked. Every offer is the supplier’s own offer: booking_token and room_allocation_id identify it, whatever room it is shown under.

Render Room Cards

Offers from different suppliers for the same physical room are grouped in one family object, split into variants by bed type. Draw one card per family:

Header: the family’s name and details (photos, size, description, amenities) labelled with details.source, for example “Photos & details: TripJack”.
Variants: show each variant’s beds, bedrooms, max_guests and smoking only from the variant object in variants[]; a null value is unknown.
Rows: one per offer, with price, meal plan and cancellation from the offer, under the variant its slot’s unifystays_room_id names. Offers listed under bed_assignment.suppliers (their slot id is the family id) go under the label Bed type assigned by the hotel. Each offer row always shows its own provider_room beds and maximum guests.

What to put on each part of the card:

Part	Take it from	Notes
Room name, photos, size, description, amenities	The family object (`name`, `details`)	All `details` come from the one supplier in `details.source`. Show it, for example “Photos & details: TripJack”.
Bed configuration of a variant	`variants[].beds`, `bedrooms`, `max_guests`, `smoking`	`null` is unknown. Never copy a bed type from one supplier’s `provider_room` onto the variant.
Offer price	`pricing.native_ledger.totals[0].total` (or `usd_ledger`, or `display_ledger` to show your display currency)	Divide `amount_minor` by 10 to the power of `currency_exponent`. Show `payable_at_property` separately as “pay at hotel”. See the price ledger.
Cancellation badge	`cancellation.refundability` and `free_cancellation_until`	Show the full `penalties` timeline on a detail view.
Meal plan and inclusions	`rooms[].meal_plan.label`, `inclusions[].label`	One per room slot.
Must-read text	`notices[]` where `must_display` is `true`	Show before the guest books.
Expiry	`lifecycle.expires_at`	Search again after it.

Display currency

Every offer’s pricing carries display_currency and display_ledger: the supplier’s native_ledger lines converted to the display currency, which is your organization’s setting or the X-Unifystays-Currency header. Read display_currency instead of assuming it. native_ledger stays the authoritative amount owed.

Field	What it means	How to use it
`pricing.display_currency`	ISO 4217 code of `display_ledger` and of every `display_*` amount.	Always read it.
`pricing.display_ledger`	The same lines as `native_ledger`, converted to `display_currency`. Same as `usd_ledger` when the display currency is USD. `null` when a rate is missing.	Show it as the guest price. Fall back to `native_ledger` when `null`.
`commercial_display`	`commercial` with every amount in `display_currency`. `null` when `commercial` is hidden.	Informational only, never add it to a ledger.
`nightly_prices[].display_amount`	The night’s amount in `display_currency`.	Optional display.
`cancellation.penalties[].display_amount`, `no_show.display_amount`	The penalty in `display_currency`.	Show next to the policy.
`deposit.display_amount`	The deposit in `display_currency`.	Show next to the deposit.

A display_* value is null when no exchange rate is available for the currency; it is never a made-up zero. Display amounts are converted with the current rate and are for showing only. The supplier charges in the native currency. Room ids:

unifystays_room_id is for display and grouping only. Book with booking_token and room_allocation_id.
A tmp_ id is valid for this search only. Do not store it.
A built room id may be retired later, when two rooms turn out to be the same room. Do not keep room ids as long-lived keys.
A later provider_options event may send a family again with different variants, bed_assignment or details: replace your copy.

Client logic:

const rooms = new Map<string, FamilyObject>(); // family unifystays_room_id -> family
const offers = new Map<string, Offer[]>(); // card key -> offers

for (const room of data.unifystays_rooms)
  rooms.set(room.unifystays_room_id, room);

source.addEventListener("provider_options", (message) => {
  const event = JSON.parse(message.data);
  for (const room of event.rooms ?? [])
    rooms.set(room.unifystays_room_id, room);
  for (const offer of event.options) {
    // One room per offer: the slot's family. Several rooms: the offer family.
    const key =
      offer.rooms.length === 1
        ? offer.rooms[0].unifystays_family_id
        : (offer.offer_family_id ?? offer.offer_id);
    offers.set(key, [...(offers.get(key) ?? []), offer]);
  }
});

For a multi-room search the card key is offer_family_id ?? offer_id and the header lists each slot’s family. An offer with offer_family_id: null contains a tmp_ room, so a multi-room offer with a tmp_ room gets its own card.

Keep the selected option’s booking_token only for the immediate prebook step; it is time-sensitive.
Connect to Stream Room Updates to obtain the bookable options and their identifiers.
Request fresh room options if the stay dates, guest mix, nationality, or selected hotel changes.

Do not cache room options or reuse their booking tokens as a checkout guarantee. Supplier-backed availability and price can change.

The OpenAPI section below provides the complete request body and response fields, including room options and stream identifiers.

Authorizations

x-api-key

string

header

required

Environment-specific API key created in the Unifystays portal

Headers

X-Unifystays-Contract-Version

enum<string>

default:2

Hotel API contract version. Optional: 2 is the current version and the default.

Available options:

2

X-Unifystays-Currency

string

ISO 4217 currency for display amounts (display_ledger, display_amount, commercial_display). Optional: defaults to your organization's display currency, USD unless configured. Read pricing.display_currency in the response.

Required string length: 3

Example:

"EUR"

Path Parameters

hotel_id

string

required

Unifystays hotel ID from hotel search or destination autocomplete (numeric string).

Example:

"123456"

Body

application/json

check_in

string

required

Check-in date (YYYY-MM-DD). Today or later. Use the same date as the hotel search.

Example:

"2026-07-01"

check_out

string

required

Check-out date (YYYY-MM-DD). Must be after check_in. Use the same date as the hotel search.

Example:

"2026-07-04"

rooms

object[]

required

One entry per room the guest needs (1 to 8). Order is preserved: slot N of every offer answers rooms[N]. Each room has adults and child_ages (use [] for no children).

Required array length: 1 - 8 elements

Show child attributes

Example:

[{ "adults": 2, "child_ages": [] }]

residency

string

Guest country of residence, ISO 3166-1 alpha-2 (for example IN). Suppliers use it for residency-restricted rates. Defaults to nationality when omitted. When both are omitted, IN is used, so always send at least one.

Example:

"IN"

nationality

string

Guest nationality, ISO 3166-1 alpha-2 (for example IN). Suppliers use it for market eligibility, pricing and booking rules. Defaults to residency when omitted. When both are omitted, IN is used, so always send at least one.

Example:

"IN"

language

string

Language code for supplier-written text (for example en). Optional. It is echoed in quote_context.language of each offer.

Example:

"en"

Response

contract_version

string

required

Response contract version, always 2.

Example:

"2"

success

boolean

required

True when the search was started.

Example:

true

message

string

required

Human-readable status. Do not parse it.

Example:

"Rooms fetched successfully"

data

object

required

The initial room response.

Show child attributes

Overview

Destination & master data

Search & hotels

Bookings

Webhook endpoints

Webhook logs

Request Example

Request Fields

Initial Response Example

Use the Response

Render Room Cards

Display currency

Authorizations

Headers

Path Parameters

Body

Response

​Request Example

​Request Fields

​Initial Response Example

​Use the Response

​Render Room Cards

​Display currency

Authorizations

Headers

Path Parameters

Body

Response

Request Example

Request Fields

Initial Response Example

Use the Response

Render Room Cards

Display currency