How to Search for Hotels in Quick Builder

Quick Builder uses the same hotel autocomplete and search endpoints as the Xeni Hotels API. This article covers the two-step process: finding a location with autocomplete, then searching for available properties.

Step 1: Autocomplete — Find a Location

Use the autocomplete endpoint to search for destinations by keyword. This returns location data and a correlation ID that you need for the property search.

Request

GET /hotels/api/v2/autocomplete?key=miami

Parameter	Type	Required	Description
`key`	string	Yes	Search keyword (city name, region, or landmark)

Response

The response returns matching locations in the data array. The critical piece is the x-correlation-id response header — you must capture this value.

JSON

{
  "data": [
    {
      "id": "place_abc123",
      "country": "US",
      "full_name": "Miami, Florida, United States",
      "location": {
        "lat": 25.7617,
        "long": -80.1918
      },
      "name": "Miami",
      "state": "Florida",
      "type": "city"
    }
  ]
}

Important: The x-correlation-id header from this response must be included in subsequent search requests. Without it, the search will fail.

Location Types

Type	Description
`city`	A specific city
`state`	A state or province
`multicity`	A region spanning multiple cities

Step 2: Search for Properties

Once you have a location and correlation ID, search for available hotel properties.

Request

POST /hotels/api/v2/properties?currency=USD&page=1&limit=50&amenities=true

Query Parameters

Parameter	Type	Required	Description
`currency`	string	Yes	Three-letter currency code (e.g., `USD`, `EUR`, `GBP`)
`page`	number	Yes	Page number for paginated results (starts at 1)
`limit`	number	Yes	Number of results per page (max 50)
`amenities`	boolean	No	Set to `true` to include amenity data in results

Headers

Header	Required	Description
`x-correlation-id`	Yes	The correlation ID from the autocomplete response
`Content-Type`	Yes	`application/json`

Request Body

JSON

{
  "checkin_date": "2026-04-15",
  "checkout_date": "2026-04-18",
  "occupancy": [
    {
      "adults": 2,
      "childs": 1,
      "childages": [
        8
      ]
    }
  ],
  "lat": 25.7617,
  "long": -80.1918,
  "countryofresidence": "US",
  "placeid": "placeabc123",
  "radius": 25,
  "sort": [
    {
      "key": "price",
      "order": "asc"
    }
  ],
  "is_async": false
}

Body Parameters

Parameter	Type	Required	Description
`checkindate`	string	Yes	Check-in date in `YYYY-MM-DD` format
`checkoutdate`	string	Yes	Check-out date in `YYYY-MM-DD` format
`occupancy`	array	Yes	Array of room occupancy objects
`occupancy[].adults`	number	Yes	Number of adults in the room
`occupancy[].childs`	number	Yes	Number of children in the room
`occupancy[].childages`	array	Conditional	Required if `childs` > 0. Array of child ages.
`lat`	number	Yes	Latitude from the autocomplete result
`long`	number	Yes	Longitude from the autocomplete result
`countryofresidence`	string	Yes	Two-letter country code of the guest
`placeid`	string	Yes	Place ID from the autocomplete result
`radius`	number	No	Search radius in kilometers (default varies by location)
`sort`	array	No	Sort criteria (see filters article for details)
`filters`	object	No	Filter criteria (see filters article for details)
`isasync`	boolean	No	Set to `true` for async mode. Default is `false`.

Correlation ID Flow

The correlation ID ties the autocomplete and search requests together. Here is the complete flow:

1. GET /hotels/api/v2/autocomplete?key=miami
   ← Response includes x-correlation-id header: "corr_xyz789"
POST /hotels/api/v2/properties?currency=USD&page=1&limit=50   → Include header: x-correlation-id: corr_xyz789
   ← Response returns hotel results

Always use the correlation ID from the most recent autocomplete call. Do not reuse correlation IDs across different searches.

Multiple Rooms

To search for multiple rooms, add additional objects to the occupancy array:

JSON

{
  "occupancy": [
    {
      "adults": 2,
      "childs": 0,
      "childages": []
    },
    {
      "adults": 2,
      "childs": 2,
      "childages": [
        5,
        10
      ]
    }
  ]
}

Each object represents one room. The search returns properties that can accommodate all specified rooms.

Next Steps

Learn how to apply filters to narrow your search results by rating, amenities, price range, and more.