Get Room Options

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

{
  "success": true,
  "message": "Static rooms loaded. Connect to SSE stream for live provider options.",
  "data": {
    "hotel_id": "123456",
    "hotel_name": "Example Hotel Dubai",
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nights": 3,
    "total_options": 0,
    "providers_queried": ["TRIPJACK"],
    "unifystays_rooms": [
      {
        "room_id": "1001",
        "room_name": "Deluxe King Room",
        "description": "Spacious room with a king bed.",
        "room_size_value": 32,
        "room_size_unit": "sqm",
        "bed_relation": "King Bed",
        "max_adults": 2,
        "max_children": 1,
        "max_occupancy": 3,
        "bed_types": null,
        "amenities": null,
        "photos": null,
        "views": null
      }
    ],
    "stream_id": "stream_8f4b9d1f6d9e",
    "sse_stream_url": "/hotels/123456/rooms/stream/stream_8f4b9d1f6d9e",
    "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" \
  -H "language: en" \
  -d '{
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ]
  }'

{
  "success": true,
  "message": "Static rooms loaded. Connect to SSE stream for live provider options.",
  "data": {
    "hotel_id": "123456",
    "hotel_name": "Example Hotel Dubai",
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nights": 3,
    "total_options": 0,
    "providers_queried": ["TRIPJACK"],
    "unifystays_rooms": [
      {
        "room_id": "1001",
        "room_name": "Deluxe King Room",
        "description": "Spacious room with a king bed.",
        "room_size_value": 32,
        "room_size_unit": "sqm",
        "bed_relation": "King Bed",
        "max_adults": 2,
        "max_children": 1,
        "max_occupancy": 3,
        "bed_types": null,
        "amenities": null,
        "photos": null,
        "views": null
      }
    ],
    "stream_id": "stream_8f4b9d1f6d9e",
    "sse_stream_url": "/hotels/123456/rooms/stream/stream_8f4b9d1f6d9e",
    "options": []
  }
}

Call this endpoint after the customer selects a hotel. Send the same dates, occupancy, and nationality used for hotel search. Unifystays calls the active suppliers in parallel and normalizes their room options. This endpoint immediately returns the hotel’s static room catalogue and a short-lived SSE stream URL. Live supplier options then arrive through that stream. Each streamed option creates the two identifiers used by the next steps:

booking_token identifies one complete supplier option and is sent to prebook.
room_allocation_id identifies one exact room slot inside that option and is later used to assign guests during booking.

Request Example

curl "$UNIFYSTAYS_BASE_URL/hotels/123456/rooms" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en" \
  -d '{
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "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.
`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.
`rooms[].child_ages`	Your occupancy form	Age of every child staying in that room. Use `[]` when there are no children.

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.

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.

{
  "success": true,
  "message": "Static rooms loaded. Connect to SSE stream for live provider options.",
  "data": {
    "hotel_id": "123456",
    "hotel_name": "Example Hotel Dubai",
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nights": 3,
    "total_options": 0,
    "providers_queried": ["TRIPJACK"],
    "unifystays_rooms": [
      {
        "room_id": "1001",
        "room_name": "Deluxe King Room",
        "description": "Spacious room with a king bed.",
        "room_size_value": 32,
        "room_size_unit": "sqm",
        "bed_relation": "King Bed",
        "max_adults": 2,
        "max_children": 1,
        "max_occupancy": 3,
        "bed_types": null,
        "amenities": null,
        "photos": null,
        "views": null
      }
    ],
    "stream_id": "stream_8f4b9d1f6d9e",
    "sse_stream_url": "/hotels/123456/rooms/stream/stream_8f4b9d1f6d9e",
    "options": []
  }
}

Use the Response

The initial response contains the static room catalogue 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 static Unifystays room catalogue for the selected hotel	Keep it while consuming the stream so mapped room IDs can resolve to full catalogue rooms.
`data.options[]`	Reserved response field; normally empty in the initial response	Read live options from `provider_options` SSE events.
`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.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	Send it unchanged to prebook. Do not create, parse, or modify it.
Stream `options[].rooms[]`	One entry per requested room instance	Render the matching Unifystays room when mapped; otherwise render `provider_room`.
`room_allocation_id`	Opaque identity for one exact room slot	Keep it associated with that slot. Prebook returns the authoritative copy used for booking.
`provider_room`	Supplier room identity and whatever static attributes are available	Use it as the fallback display room when `unifystays_room` is null.
`mapping_status`	`MAPPED`, `AMBIGUOUS`, `UNMAPPED`, or `CONFLICT`	Use for display or diagnostics only. It does not determine bookability.
`mapping_details`	Mapping source, confidence, algorithm version, and reason codes	Use for diagnostics and observability; do not use it as booking identity.
`unifystays_room`	Complete static Unifystays room snapshot, or null	Prefer it for display when present. Never use it as booking identity.
`occupancy`	Adults and child ages quoted for this allocation	Keep guest assignment compatible with this occupancy.

mapping_status: "UNMAPPED" and unifystays_room: null do not make an option unbookable. Supplier-to-catalogue room matching is best-effort. The booking flow uses booking_token and room_allocation_id, which are created for every quoted room regardless of mapping status.

The mapper evaluates each supplier’s complete hotel room lineup rather than matching every room name independently. It combines semantic room attributes, hotel-local distinguishing phrases, and a globally stable one-to-one assignment. Successful mappings are persisted and reused. Name-only suppliers use an internal deterministic fingerprint, while their public provider_room.id remains null. Compact semantic signatures on mapping rows allow independently verified suppliers to confirm the same core-room target.

Choose the Room Object to Render

Each streamed room already carries its mapped unifystays_room snapshot. If it is null, render provider_room. Do not perform a client-side catalogue join and do not hide an option because a static mapping is unavailable.

const roomToRender = streamedRoom.unifystays_room ?? streamedRoom.provider_room;

The two room shapes are intentionally different. A mapped Unifystays room uses fields such as room_name, photos, and max_occupancy; a provider room uses name, images, and occupancy.max_allowed. Adapt both shapes to your own UI view model after selecting the fallback.

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:1

Hotel API contract version. Missing defaults to v1.

Available options:

1

Path Parameters

hotel_id

string

required

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

Example:

"123456"

Body

application/json

check_in

string

required

Check-in date in YYYY-MM-DD format. Must be today or a future date.

Example:

"2026-07-01"

check_out

string

required

Check-out date in YYYY-MM-DD format. Must be after check_in.

Example:

"2026-07-04"

residency

string

required

Guest country of residence — ISO alpha-2 code. Used for residency-restricted rates.

Example:

"IN"

rooms

object[]

required

Room configurations — 1 to 8 rooms. Each room specifies adults and optional child ages.

Required array length: 1 - 8 elements

Show child attributes

Example:

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

nationality

string

Guest citizenship/nationality — ISO alpha-2 code. Defaults to residency when omitted.

Example:

"IN"

language

string

Requested response language (for example en).

Example:

"en"

Response

contract_version

string

required

Example:

"1"

success

boolean

required

Example:

true

message

string

required

Example:

"Rooms fetched successfully"

data

object

required

Show child attributes

Overview

Destination & master data

Search & hotels

Bookings

Webhook endpoints

Webhook logs

Request Example

Request Fields

Initial Response Example

Use the Response

Choose the Room Object to Render

Authorizations

Headers

Path Parameters

Body

Response

​Request Example

​Request Fields

​Initial Response Example

​Use the Response

​Choose the Room Object to Render

Authorizations

Headers

Path Parameters

Body

Response

Request Example

Request Fields

Initial Response Example

Use the Response

Choose the Room Object to Render