Skip to Content
OpenRoam Docs
Hotels

Search hotels

Searches hotels by location or hotel IDs and returns their bookable rates for the stay.

POST
/v1/hotels/search

Searches hotels by location or hotel IDs and returns their bookable rates for the stay.

Send searchCriteria.location or searchCriteria.hotelIds; a non-empty hotelIds wins and location is then ignored. checkIn, checkOut, rooms and guestNationality are required: rates are priced for the occupancy, child ages and guest market sent here. A stay longer than 30 nights returns 400 / 10001 with reason MAX_STAY_EXCEEDED at checkOut. The body rejects an unknown member at every level, filters, searchCriteria.location and rooms[] included, and the route takes no query parameters: either gives 400 / 10001.

Returns { items, pagination, nextCursor, details }. Each item is a hotel: id, name, countryCode, category (always null), logoUrl (the main image), description, its offers, and details with the star rating, address, coordinates, images, amenity groups and contact. Each offer is one rate: an opaque publicId, a name such as "Deluxe King, Breakfast, Free cancellation", a price for the whole stay (all rooms and nights), and the rate terms in details, including expiresAt. Pass an offer's publicId to quote or order before it expires. The hotel's id is not an offer; send it in searchCriteria.hotelIds to search that hotel again. A hotel without an orderable offer is not listed. details.availableFilters holds the amenity filter values of a cityCode search.

Location searches are paged: limit is 1–50 (default 20) and the next page is requested by sending the response's nextCursor back as cursor with the same body; a null nextCursor is the last page. A page can hold fewer hotels than limit, even none, while nextCursor is not null: keep paging until it is null. pagination is { currentCount, limit, hasMore }: the walk states no page number and no total. To keep pages small, each hotel on a page has one offer, its cheapest rate, with empty nightlyPrices and surcharges, and no description and one image. A hotelIds search returns every rate of those hotels with the full detail, as one complete page; an empty items there means none of those hotels has an orderable offer.

Errors: an ID that is not a hotel ID returns 400 / 21000; an unknown or expired hotel ID 400 / 11004; 503 / 21003 when offers are temporarily unavailable (retry the search); 502, 504 or 503 with 21007–21009 when the hotel system fails, times out or is unavailable.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Request Body

  1. body

Hotel search: where to search, the stay, the rooms, the guest market and the price currency.

searchCriteria?|

What to search: location or hotelIds. Required.

checkIn*string

Check-in date (yyyy-MM-dd), the hotel's local date: today or later there. Only a date that has ended everywhere is refused; availability decides the rest.

Formatdate
checkOut*string

Check-out date (yyyy-MM-dd); after checkIn, at most 30 nights later.

Formatdate
rooms*array<>

One entry per room, 1–9 rooms. Each room is matched by its 1-based position when ordering.

guestNationality*|

Guests' nationality as a two-letter ISO 3166-1 alpha-2 code, for example AE. Required: rates are priced for this market.

guestCountryOfResidence?|

Guests' country of residence as a two-letter ISO 3166-1 alpha-2 code. Optional; defaults to guestNationality.

filters?|

Optional filters on star rating, price, board type and amenities.

cursor?|

Location searches only: the previous response's nextCursor, to get the next page. Opaque; do not build or change it. A malformed cursor returns 400.

limit?|

Location searches only: hotels per page, 1–50 (default 20); larger values are capped at 50.

Formatint32
currency?|

Three-letter ISO 4217 price currency; the API key's currency when omitted.

Response Body

OK

  1. response

One page of hotels with their offers. A location search is paged with nextCursor; a hotelIds search is one complete page. A hotel without an orderable offer is not listed.

items*array<>

The hotels of this page, each with its offers.

pagination*

Where this page sits. A location search walks the area's hotels with a cursor, so it states no page number and no total.

nextCursor?|

Send it back as cursor, with the same body, for the next page; null on the last page. A location page can hold fewer hotels than the limit, even none, while it is set.

details*

Hotel search facts outside the keys every partner service shares.

curl -X POST 'https://api.sandbox.openroam.com/v1/hotels/search' \  -H 'Content-Type: application/json' \  -d '{  "searchCriteria": {    "location": {      "geoNodeId": "42ea4cba-6d1b-1c24-9428-b2c2678b1062"    }  },  "checkIn": "2026-12-10",  "checkOut": "2026-12-13",  "rooms": [    {      "adults": 2,      "children": 1,      "childrenAges": [        7      ]    }  ],  "guestNationality": "GB",  "currency": "USD",  "filters": {    "minStarRating": 4,    "boardTypes": [      "breakfast"    ],    "maxPrice": 900  },  "limit": 20}'
Example Response
{  "items": [    {      "id": "hotel_q7m2k4t6v3x5z2b4d6f3h5jn2p",      "name": "Hotel Arts Barcelona",      "countryCode": "ES",      "category": null,      "logoUrl": "https://cdn.openroam.test/hotels/hotel_q7m2k4t6v3x5z2b4d6f3h5jn2p/1c3fc0de.jpg",      "description": "<p>A seafront tower in the Olympic Port.</p>",      "offers": [        {          "publicId": "rate_x5z2b4d6f3h5jn2pq7m2k4t6v3",          "name": "Deluxe King, Breakfast, Free cancellation",          "description": null,          "price": {            "amount": 642.1,            "currency": "USD"          },          "details": {            "expiresAt": "2026-12-01T10:30:00Z",            "rooms": [              {                "roomGroupKey": "4c8e3ae1d379f759bc372243",                "name": "Deluxe King",                "description": null,                "beds": [],                "maxOccupancy": 3,                "sizeSquareMeters": null,                "amenities": [],                "imageUrls": [],                "roomIndex": 1,                "adultsCount": 2,                "childrenCount": 1,                "childrenAges": [                  7                ]              }            ],            "board": {              "code": "BB",              "name": "Bed and breakfast",              "boardType": "breakfast"            },            "terms": {              "payment": {                "type": "payNow",                "dueNow": {                  "amount": 642.1,                  "currency": "USD"                },                "dueLater": null,                "dueLaterAt": null              },              "cancellation": {                "type": "fullyRefundable",                "freeUntil": "2026-12-08T23:59:00Z",                "freeUntilLocalTime": "2026-12-09T00:59:00",                "timezone": "Europe/Madrid",                "schedule": [                  {                    "from": "2026-12-08T23:59:00Z",                    "fromLocalTime": "2026-12-09T00:59:00",                    "refund": {                      "amount": 428.07,                      "currency": "USD"                    },                    "penalty": {                      "amount": 214.03,                      "currency": "USD"                    }                  }                ],                "fee": null              },              "changes": {                "allowed": true,                "fee": null              }            },            "taxes": {              "included": true,              "totalTaxAmount": 41.2,              "items": []            },            "priceIsBinding": true,            "nightlyPrices": [              {                "date": "2026-12-10",                "amount": 214.03,                "currency": "USD"              },              {                "date": "2026-12-11",                "amount": 214.03,                "currency": "USD"              },              {                "date": "2026-12-12",                "amount": 214.04,                "currency": "USD"              }            ],            "surcharges": [              {                "type": "AtProperty",                "description": "City Tax",                "price": {                  "amount": 12.45,                  "currency": "EUR"                },                "approxPrice": {                  "amount": 13.5,                  "currency": "USD"                },                "includedInTotal": false,                "payableAt": "property"              }            ],            "rateTags": [],            "remarks": [],            "withTransfers": false,            "rateRules": [],            "amendabilityStatus": "yes",            "guestNameRules": {              "minLength": 1,              "maxLength": 50,              "pattern": "^(?=.*[a-zA-Z])[a-zA-Z\\s\\-'\\.]+$",              "allowedCharacters": "letters, spaces, hyphens, apostrophes and periods",              "distinctFullNames": false            }          }        }      ],      "details": {        "starRating": 5,        "address": {          "line1": "Carrer de la Marina 19-21",          "line2": null,          "city": "Barcelona",          "stateProvince": null,          "postalCode": "08005",          "countryCode": "ES",          "countryName": null        },        "coordinates": {          "latitude": 41.386,          "longitude": 2.196        },        "imageUrls": [          "https://cdn.openroam.test/hotels/hotel_q7m2k4t6v3x5z2b4d6f3h5jn2p/7a90c0de.jpg"        ],        "amenityGroups": [          {            "key": "PropertyAmenities",            "codes": [              "FreeWifi",              "Pool"            ]          }        ],        "contact": null,        "displayGroup": null      }    }  ],  "pagination": {    "currentCount": 1,    "limit": 1,    "hasMore": false  },  "nextCursor": null,  "details": {    "availableFilters": null  }}

Quote hotel rates POST

Prices up to 5 searched or quoted rates again with the hotel system and issues a new offer for each. Takes the same body as order, `{ currency, referenceId, items }`, and checks it the same way: the whole body first, so a body error gives 400 / 10001 also when it is in a later item, then each item completely (its inputs, its `publicId`, then a fresh price from the hotel system) before the next, in request order. `inputs` may be left out; when sent, they are checked as the order checks them. The body and every object in it reject an unknown member (400 / 10001). Stay dates and rooms come from the offer and are returned in each item's `details`. Nothing is charged or reserved. Each item returns a new `publicId` for its rate at the current `price` (the whole stay, all rooms and nights): order with it before `details.expiresAt`, which is at most 30 minutes away and never past an expiry the hotel system states. A price that rose since the search is returned with 200; only `inputs.maxPrice` stops a quote, with 409 / 11002 at `items[i].inputs.maxPrice`. `details.availability` is `onRequest` for a rate that is held only on request, which an order refuses with 409 / 11003. Errors name the failing item: a rate that is no longer sold is 409 / 11003, and an unknown, expired or another partner's `publicId`, another product's offer, a hotel's own `id` or an expired search session (search again) is 400 / 11004, each at `items[i]`; input errors (400 / 10001) are at `items[i].inputs…`. Offer and hotel-system failures return their hotel codes without a path: 503 / 21003 when offers are temporarily unavailable, 21007–21009, and 400 / 21010 when the hotel's room layout no longer matches the searched occupancy (search again).

Approve a manual amendment POST

Approves the quoted price of a manual amendment and settles it from your wallet. Requires an `Idempotency-Key` header (a UUID). Only a `Quoted` request can be approved: show the quoted `amountToPay` or `amountToRefund` first. On approval `amountToPay` is debited and the request becomes `PartnerApproved`; `amountToRefund` is credited only after the change is confirmed. The body is optional; `walletId` picks the wallet to settle from. Returns `{ amendmentId }`. Errors: 400 / 21103 when the request is not `Quoted`; 400 / 21107 when the wallet balance is too low (the request stays `Quoted`; top up and approve again); 400 / 21106 when changing the wallet while an approval is in progress; 21105 or 21108–21112 for settlement and concurrency failures (reload the request and contact support before retrying a 21108). The same key and body after the approval finished returns `{ amendmentId }` again and approves and charges nothing again. While it is still running the key gives 409 / 12002 with `Retry-After`, and with a different body 409 / 12001.