Skip to Content
OpenRoam Docs
Hotels

List hotel amenities

Returns the amenity catalog: every amenity code and group with its display label.

GET
/v1/hotels/amenities/catalog

Returns the amenity catalog: every amenity code and group with its display label.

Use it to label the amenityGroups codes in hotel content and to build an amenity filter; send codes back in search filters.amenityCodes. notesLabel is the heading for a hotel's uncoded amenityNotes. Labels follow the request language, as Accept-Language sets it; the route takes no query parameters.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Response Body

OK

  1. response
mapVersion*integer

Version of the amenity catalog the labels and codes come from.

Formatint32
groups*array<>

Every amenity group, labelled, with the codes it holds.

amenities*array<>

Every amenity code with its label, for rendering a card or a rail.

notesLabel*string

Heading for a card's amenityNotes. Those strings are free text with no code, so unlike every other label on a card this one cannot be looked up from Amenities.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/hotels/amenities/catalog'
Example Response
{  "mapVersion": 0,  "groups": [    {      "key": "string",      "label": "string",      "codes": [        "string"      ]    }  ],  "amenities": [    {      "code": "string",      "label": "string"    }  ],  "notesLabel": "string"}

Book hotels POST

Places and pays for hotel bookings of up to 5 searched or quoted rates. Requires an `Idempotency-Key` header (a new UUID per purchase) and an API key with order-manage permission. Repeating the same request with the same key returns the original order; while the first request is still running the response is 409 / 12002 with `Retry-After`, after which you send the same request again. The order is paid from your wallet balance and each booking completes asynchronously: track it with `GET /orders/{id}` or the `order.fulfillment.updated` webhook. The body is `{ currency, referenceId, items }` with 1 to 5 items, each `{ publicId, quantity, inputs }`. `publicId` is an offer's `publicId` from search, or the newer one from quote, and `quantity` must be 1. `inputs` holds the holder and one `roomGuests` entry per searched room (`roomIndex` 1 to N), whose guests must match the searched occupancy and child ages, the optional `specialRequests`, and the optional price guard `maxPrice` in the order currency. Unknown fields are rejected with 400. The whole body is validated first: a body error gives 400 / 10001, also when it is in a later item. Once the body is valid, each item is checked completely before the next, and an error names its item in `details[].path`. Before any money moves each rate is priced again in the order currency and capped: at `inputs.maxPrice` when sent, else at the price shown with the `publicId`. Above the cap the order returns 409 / 11002 at `items[i].inputs.maxPrice` or `items[i]` (quote again); at or below it the rate is charged as priced, so a `maxPrice` above the shown price accepts a rise up to it. A rate that cannot be booked now returns 409 / 11003, an offer priced in another currency than the order 400 / 11005, and an unknown, expired or another partner's `publicId` 400 / 11004, each at `items[i]`. Offer and hotel-system failures return their hotel codes (21003, 21007–21010) without a path. A wallet charge that fails gives 402 / 16000, with `details[0]` naming `wallet` and `INSUFFICIENT_BALANCE` or `WALLET_BLOCKED`; send the same request with the same key after a top-up. Nothing is created or charged when the order is refused.

Get hotel catalog files GET

Returns download links for the current hotel catalog files. Returns `{ generatedAt, hotelCount, files: [{ variant, url, sizeBytes }] }`, one zip per variant. Each zip holds `hotels.jsonl`: one hotel per line, in the item shape that search and `properties/{id}` return, with `offers` empty. `withoutImages` carries each hotel's main image as `logoUrl` and an empty `details.imageUrls`; `withImages` also lists every gallery image there. `generatedAt` is null and `files` empty before the first catalog is built, and after a release that changes the line format until the first build in the new format: the route never links a file whose lines have another format. The route takes no query parameters.