Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Booking Engine

Build your own booking flow on your website. You need two calls:

  1. Check availability for the guest's stay: which rooms can be booked, and for how much.

  2. Create the booking for the room the guest picks.

Both use your API key. See Authentication.

Step 1: Check availability

GET /api/v1/client/availability
curl "https://api.hostelmate.co/api/v1/client/availability?check_in=2026-11-02&check_out=2026-11-05&guests=2" \
  -H "X-API-Key: <your_api_key>"
Parameter
Type
Description

check_in

string

Required. First night of the stay (YYYY-MM-DD).

check_out

string

Required. Departure day (YYYY-MM-DD). A stay from the 2nd to the 5th is 3 nights.

guests

integer

Number of guests, 1 to 50 (default: 1).

You get every room your booking page shows. For each room:

  • whether the whole stay can be booked (bookable);

  • the total;

  • each night's price and free beds.

It's the same answer your own booking page gives a guest for those dates. Prices are integers in minor units: 2500 = 25.00.

The answer also carries your rooms' photos and descriptions, your property details, payment methods and booking page settings, so you can build the whole page from this one call.

Every field, rule and error code is on the Availability page.

Step 2: Create the booking

Pick a room with "bookable": true and send it to Booking Create. From availability to a booking explains:

  • how to pass the nights and prices;

  • what to do for several guests in a dorm;

  • what to do if the beds are taken in between.


Note: POST /api/v1/get-new-avilablilty is a legacy endpoint and will be retired soon. It still works for now, but it gets no new features.

If you're still using get-new-avilablilty, please move to Availability. You only change the URL to https://api.hostelmate.co/api/v1/client/availability and add your X-API-Key header. Your request body and your code stay the same: every field you read today comes back with the same name and value, and photo links point to the same photos on cdn.hostelmate.co. See Moving from get-new-avilablilty.

Last updated