Search Hotels

curl "$UNIFYSTAYS_BASE_URL/hotels/search" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en" \
  -d '{
    "destination": {
      "type": "place",
      "id": 101
    },
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ],
    "star_ratings": [4, 5],
    "limit": 20,
    "pricing_mode": "instant",
    "sort": "recommended"
  }'

{
  "contract_version": "1",
  "success": true,
  "message": "Hotels fetched successfully",
  "data": {
    "search_info": {
      "country_code": "IN",
      "check_in": "2026-07-01",
      "check_out": "2026-07-04",
      "nights": 3,
      "total_rooms": 2,
      "total_guests": 5,
      "price_sort": "recommended",
      "hotel_id": "1892345",
      "hotel": "Example Hotel",
      "place_id": 2930267,
      "place": "Bali",
      "place_type": "region"
    },
    "total_results": 42,
    "requested_results": 20,
    "returned_results": 20,
    "hotels": [
      {
        "hotel_id": "123456",
        "hotel_name": "The Taj Mahal Palace",
        "city": "Mumbai",
        "country": "India",
        "facilities": [
          "Free WiFi",
          "Swimming pool",
          "Breakfast"
        ],
        "availability_band": 0,
        "price": {
          "amount": 275000,
          "currency": "USD",
          "rate_type": "live",
          "is_refundable": true,
          "free_cancellation_until": "2026-08-25T23:59:59.000Z"
        },
        "supplier_prices": [
          {
            "hotel_id": "123456",
            "supplier_code": "REZLIVE",
            "supplier_name": "RezLive",
            "amount": 28500,
            "currency": "USD",
            "rate_type": "live",
            "fetched_at": "2026-08-19T05:30:02.000Z",
            "is_refundable": true,
            "free_cancellation_until": "2026-08-25T23:59:59.000Z"
          }
        ],
        "stars": 5,
        "address": "Apollo Bunder, Colaba",
        "latitude": 18.9217,
        "longitude": 72.8332,
        "main_image_url": "https://cdn.example.com/hotels/taj.jpg",
        "chain": "Marriott",
        "distance_from_center_km": 2.1,
        "value_pct": 18,
        "typical_price_usd_cents": 168000,
        "vs_typical_pct": 22
      }
    ],
    "search_id": "srch_a1b2c3d4e5f6g7h8",
    "refresh_status": "PENDING",
    "next_cursor": "1012.4_1283771",
    "similar_hotels": [
      {
        "hotel_id": "123456",
        "hotel_name": "The Taj Mahal Palace",
        "city": "Mumbai",
        "country": "India",
        "facilities": [
          "Free WiFi",
          "Swimming pool",
          "Breakfast"
        ],
        "availability_band": 0,
        "price": {
          "amount": 275000,
          "currency": "USD",
          "rate_type": "live",
          "is_refundable": true,
          "free_cancellation_until": "2026-08-25T23:59:59.000Z"
        },
        "supplier_prices": [
          {
            "hotel_id": "123456",
            "supplier_code": "REZLIVE",
            "supplier_name": "RezLive",
            "amount": 28500,
            "currency": "USD",
            "rate_type": "live",
            "fetched_at": "2026-08-19T05:30:02.000Z",
            "is_refundable": true,
            "free_cancellation_until": "2026-08-25T23:59:59.000Z"
          }
        ],
        "stars": 5,
        "address": "Apollo Bunder, Colaba",
        "latitude": 18.9217,
        "longitude": 72.8332,
        "main_image_url": "https://cdn.example.com/hotels/taj.jpg",
        "chain": "Marriott",
        "distance_from_center_km": 2.1,
        "value_pct": 18,
        "typical_price_usd_cents": 168000,
        "vs_typical_pct": 22,
        "distance_km": 1.2
      }
    ]
  }
}

POST

hotels

curl "$UNIFYSTAYS_BASE_URL/hotels/search" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en" \
  -d '{
    "destination": {
      "type": "place",
      "id": 101
    },
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ],
    "star_ratings": [4, 5],
    "limit": 20,
    "pricing_mode": "instant",
    "sort": "recommended"
  }'

{
  "contract_version": "1",
  "success": true,
  "message": "Hotels fetched successfully",
  "data": {
    "search_info": {
      "country_code": "IN",
      "check_in": "2026-07-01",
      "check_out": "2026-07-04",
      "nights": 3,
      "total_rooms": 2,
      "total_guests": 5,
      "price_sort": "recommended",
      "hotel_id": "1892345",
      "hotel": "Example Hotel",
      "place_id": 2930267,
      "place": "Bali",
      "place_type": "region"
    },
    "total_results": 42,
    "requested_results": 20,
    "returned_results": 20,
    "hotels": [
      {
        "hotel_id": "123456",
        "hotel_name": "The Taj Mahal Palace",
        "city": "Mumbai",
        "country": "India",
        "facilities": [
          "Free WiFi",
          "Swimming pool",
          "Breakfast"
        ],
        "availability_band": 0,
        "price": {
          "amount": 275000,
          "currency": "USD",
          "rate_type": "live",
          "is_refundable": true,
          "free_cancellation_until": "2026-08-25T23:59:59.000Z"
        },
        "supplier_prices": [
          {
            "hotel_id": "123456",
            "supplier_code": "REZLIVE",
            "supplier_name": "RezLive",
            "amount": 28500,
            "currency": "USD",
            "rate_type": "live",
            "fetched_at": "2026-08-19T05:30:02.000Z",
            "is_refundable": true,
            "free_cancellation_until": "2026-08-25T23:59:59.000Z"
          }
        ],
        "stars": 5,
        "address": "Apollo Bunder, Colaba",
        "latitude": 18.9217,
        "longitude": 72.8332,
        "main_image_url": "https://cdn.example.com/hotels/taj.jpg",
        "chain": "Marriott",
        "distance_from_center_km": 2.1,
        "value_pct": 18,
        "typical_price_usd_cents": 168000,
        "vs_typical_pct": 22
      }
    ],
    "search_id": "srch_a1b2c3d4e5f6g7h8",
    "refresh_status": "PENDING",
    "next_cursor": "1012.4_1283771",
    "similar_hotels": [
      {
        "hotel_id": "123456",
        "hotel_name": "The Taj Mahal Palace",
        "city": "Mumbai",
        "country": "India",
        "facilities": [
          "Free WiFi",
          "Swimming pool",
          "Breakfast"
        ],
        "availability_band": 0,
        "price": {
          "amount": 275000,
          "currency": "USD",
          "rate_type": "live",
          "is_refundable": true,
          "free_cancellation_until": "2026-08-25T23:59:59.000Z"
        },
        "supplier_prices": [
          {
            "hotel_id": "123456",
            "supplier_code": "REZLIVE",
            "supplier_name": "RezLive",
            "amount": 28500,
            "currency": "USD",
            "rate_type": "live",
            "fetched_at": "2026-08-19T05:30:02.000Z",
            "is_refundable": true,
            "free_cancellation_until": "2026-08-25T23:59:59.000Z"
          }
        ],
        "stars": 5,
        "address": "Apollo Bunder, Colaba",
        "latitude": 18.9217,
        "longitude": 72.8332,
        "main_image_url": "https://cdn.example.com/hotels/taj.jpg",
        "chain": "Marriott",
        "distance_from_center_km": 2.1,
        "value_pct": 18,
        "typical_price_usd_cents": 168000,
        "vs_typical_pct": 22,
        "distance_km": 1.2
      }
    ]
  }
}

Hotel search is the shopping entry point for your enabled suppliers. Start with a destination returned by Destination Autocomplete and use the guest nationality iso_code returned by Nationalities.

Sandbox/staging has a deliberately limited place and hotel dataset. Search with a destination returned by the same environment’s autocomplete endpoint. An ID copied from production or another environment may return no hotels even when the request is otherwise valid.

Request Example

curl "$UNIFYSTAYS_BASE_URL/hotels/search" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "language: en" \
  -d '{
    "destination": {
      "type": "place",
      "id": 101
    },
    "check_in": "2026-09-12",
    "check_out": "2026-09-15",
    "nationality": "IN",
    "rooms": [
      {
        "adults": 2,
        "child_ages": []
      }
    ],
    "star_ratings": [4, 5],
    "limit": 20,
    "pricing_mode": "instant",
    "sort": "recommended"
  }'

Destination and Guest Inputs

Input	Source	Integration rule
`destination.type` and `destination.id`	Destination autocomplete	Keep the selected type and send its matching hotel or place ID.
`nationality`	Nationalities	Send the selected ISO alpha-2 `iso_code`.
`rooms`	Your guest form	Send 1–8 rooms with each room’s adults and child ages; keep the same occupancy for room options.
Stay dates	Your guest form	Send dates in `YYYY-MM-DD` format.

Pricing Modes

Mode	Behavior	Recommended use
`instant`	Returns cached or estimated prices quickly, then refreshes supplier prices in the background.	Customer-facing result pages.
`live`	Waits up to roughly 15 seconds for supplier refresh in the search response.	Low-volume or machine-to-machine rate shopping.

When using instant, retain data.search_id and poll Get Search Price Updates every two seconds while results are visible.

Search Price Currency

price.amount and each supplier_prices[].amount are integer cents in their accompanying currency. USD is the default. Accounts with a EUR hotel-list override receive EUR for these prices in POST /hotels/search, including live quotes and similar hotels. Conversion uses the stored active exchange rate; an unavailable rate returns HTTP 503 rather than an incorrectly labelled price. This override applies only to the hotel-list response. Price polling, room options, prebooking, and booking keep their existing currencies. Fields explicitly named in USD, including typical_price_usd_cents and USD price filters, remain USD cents. Always read each price’s currency when displaying or comparing it.

Tenant-Specific Availability

Search results are evaluated against the suppliers enabled for your OTA account. A hotel returned in the current search is not removed later when the background refresh reports no price; use no_price_hotel_ids from the price updates endpoint to decide how that hotel should appear in your UI. Future searches may omit hotels with recent or repeated no-price results for your account and current supplier set. An exact no-price result is remembered for 30 minutes. A hotel is treated as chronically unavailable after no-price results on three distinct check-in dates in 14 days. A later live supplier price resets that history. This history is isolated by OTA account, environment, and enabled supplier set, and supplier errors or timeouts do not count as no-price evidence.

Pagination and Rendering

Use data.next_cursor as cursor in the next request. Keep the original search inputs when paging.
Use the requested sort consistently across cursor pages.
Merge live updates by hotel_id and re-sort when price changes arrive.
Render similar_hotels as a separate nearby-properties section rather than mixing it into the main result list.
Use fields only when a smaller payload is intentional; hotel_id remains available for merging and selection.

Search prices are shopping data, not a booking confirmation. Request fresh room options for the chosen hotel and prebook immediately before booking.

The OpenAPI section below documents every search filter, occupancy constraint, sort option, response field, and error response.

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

Body

application/json

destination

object

required

Selected destination from the autocomplete widget. Supply the type and id exactly as returned by GET /destinations/autocomplete.

Show child attributes

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"

rooms

object[]

required

Room configurations. Minimum 1 room, maximum 8 rooms. Each room supports up to 5 total occupants (adults + children).

Required array length: 1 - 8 elements

Show child attributes

star_ratings

number[][]

Filter results by star ratings. Pass one or more values from 1–5.

Example:

[4, 5]

price_min_usd_cents

number

Minimum TOTAL price filter in USD cents (across all nights/rooms). Server converts to nightly unit range using computed stay multiplier.

Required range: x >= 0

Example:

5000

price_max_usd_cents

number

Maximum TOTAL price filter in USD cents.

Required range: x >= 1

Example:

500000

property_types

string[][]

Filter by property type. Values come from GET /hotels/filters → property_types.

Example:

["Hotel", "Resort"]

chain_ids

number[][]

Filter by hotel chain IDs. Values come from GET /hotels/filters → chains.

Example:

[42, 99]

facility_ids

number[][]

Filter by facility IDs (matches hotels.facilities[].facility_id). Multiple ids are ANDed — hotel must have all selected facilities. Values come from GET /hotels/filters → facilities.

Example:

[107, 25]

hotel_name

string

Free-text hotel name filter. Server runs ILIKE "%name%".

Example:

"marriott"

hotel_ids

number[][]

Filter by specific hotel IDs. Useful when user wants to narrow the result set to one or more particular hotels (e.g. after picking from autocomplete). Matches hotels.hotel_id.

Example:

[1892345, 2031122]

nationality

string

default:IN

Nationality of the guest in ISO alpha-2 format (e.g. IN for Indian, US for United States).

Example:

"IN"

language

string

Requested response language. Forwarded to suppliers such as Leamigo.

Example:

"en"

limit

number

default:20

Requested hotels per page. If omitted, default page size is used.

Required range: 1 <= x <= 100

Example:

20

cursor

string

Cursor token for next-page fetch in format "sortKey_hotelId". Pass the next_cursor returned in previous response.

Example:

"1037.5_1892345"

price_sort

enum<string>

default:recommended

Price sort direction for listing page. Uses precomputed sort_price_usd_cents for stable cursor pagination. If omitted, API uses recommended ranking (tier/cache/reliability first).

Available options:

low_to_high,

high_to_low

Example:

"low_to_high"

pricing_mode

enum<string>

default:instant

'instant' (default): returns cached/estimated prices immediately; poll GET /hotels/search/:searchId/prices for live supplier prices. 'live': the request waits (up to ~15s) for the live supplier refresh and returns all supplier quotes collected in supplier_prices in this single call. The server does not choose the lowest quote.

Available options:

instant,

live

Example:

"instant"

sort

enum<string>

default:recommended

Sort order. Supersedes price_sort when both are sent. recommended (default) = neutral relevance ranking; price_low_to_high / price_high_to_low = by total price; stars = star rating high→low; distance_from_center = closest to the searched place centre first; value = best value_pct deals first.

Available options:

recommended,

price_low_to_high,

price_high_to_low,

stars,

distance_from_center,

value

Example:

"distance_from_center"

fields

string[]

Sparse fieldset: return only these hotel-item fields (hotel_id is always included). Unknown names are ignored. Trims payloads for mobile / high-volume callers. Example: ["hotel_name","price","stars"].

Example:

["hotel_name", "price", "stars"]

Response

contract_version

string

required

Example:

"1"

success

boolean

required

Example:

true

message

string

required

Example:

"Hotels fetched successfully"

data

object

required

Show child attributes

Overview

Destination & master data

Search & hotels

Bookings

Webhook endpoints

Webhook logs

Request Example

Destination and Guest Inputs

Pricing Modes

Search Price Currency

Tenant-Specific Availability

Authorizations

Headers

Body

Response

​Request Example

​Destination and Guest Inputs

​Pricing Modes

​Search Price Currency

​Tenant-Specific Availability

​Pagination and Rendering

Authorizations

Headers

Body

Response

Request Example

Destination and Guest Inputs

Pricing Modes

Search Price Currency

Tenant-Specific Availability

Pagination and Rendering