How to add hotel search to your website

This guide adds hotel search, rates, and booking to your site. It combines place search, availability, rate validation, and the booking flow.

Before you start

A SessionId. See authentication.
The hotel permissions: hotel_availability, hotel_check_rate, hotel_book, hotel_order.

Step 1: Turn a destination into an id

Place search is public, so you can wire it straight to a type-ahead box. Keep the external_id of the chosen place.

curl "https://api.hermeseus.com/api/v2/Hotel/cities/search?q=paris&type=city"

Step 2: List properties

Search the place for stay dates and guests. Show the results, then let the user filter and sort.

curl -X POST https://api.hermeseus.com/api/v2/Hotel/HotelAvailability \
  -H "Content-Type: application/json" \
  -d '{
    "SessionId": "8f3c81d2-...",
    "CheckIn": "2026-10-15", "CheckOut": "2026-10-16",
    "CityId": 11111111456928,
    "Occupancies": [ { "AdultCount": 2 } ],
    "Sort": "price"
  }'

Step 3: Open a hotel and pick a room

Re-call the same endpoint with CityId set to null and the chosen HotelId. Each room rate carries a FareSourceCode. Keep the one the traveller picks.

curl -X POST https://api.hermeseus.com/api/v2/Hotel/HotelAvailability \
  -H "Content-Type: application/json" \
  -d '{
    "SessionId": "8f3c81d2-...",
    "CheckIn": "2026-10-15", "CheckOut": "2026-10-16",
    "CityId": null, "HotelId": 7825691,
    "Occupancies": [ { "AdultCount": 2 } ]
  }'

Step 4: Validate the rate

At checkout, re-price the room. The validated rate holds for 15 minutes. Book with the FareSourceCode this returns.

curl -X POST https://api.hermeseus.com/api/v2/Hotel/HotelCheckRate \
  -H "Content-Type: application/json" \
  -d '{ "SessionId": "8f3c81d2-...", "FareSourceCode": "YmE6OTk4MjE6cnI3ZjMy" }'

Step 5: Book, then place the order

Book to hold the room. Nothing is charged yet. After the traveller pays you, place the order to confirm and charge.

# hold
curl -X POST https://api.hermeseus.com/api/v2/Hotel/HotelBook \
  -H "Content-Type: application/json" \
  -d '{
    "SessionId": "8f3c81d2-...", "FareSourceCode": "YmE6OTk4MjE6cnI3ZjMy",
    "PhoneNumber": "+441234567890", "Email": "traveller@example.com",
    "Rooms": [ { "Passengers": [ { "FirstName": "Jane", "LastName": "Doe", "PassengerType": 1, "PassengerTitle": 2 } ] } ],
    "HotelTransfers": []
  }'

# confirm and charge
curl -X POST https://api.hermeseus.com/api/v2/Hotel/HotelOrder \
  -H "Content-Type: application/json" \
  -d '{ "SessionId": "8f3c81d2-...", "UniqueId": "HB-2026-004417" }'

Handle the common failures

Err0201003 at availability: send exactly one of CityId or HotelId.
Err0102003 at book or order: the rate lapsed. Validate again.

Full field lists are on the hotel reference pages.