Search and book
The standard way to sell: search for a stay and a party, show your client the offers, and book the one they choose. The search prices everything with the hotel's own engine, the same one behind the hotel's website, so the price you book is exactly the price you showed.
POST /search
{
"locale": "en",
"checkin_date": "2026-07-14",
"checkout_date": "2026-07-21",
"occupancy": [
{ "adults": 2, "children": [7, 4] },
{ "adults": 2 }
],
"properties": [1860]
}
| Field | Required | |
|---|---|---|
locale |
yes | Language of the texts |
checkin_date, checkout_date |
yes | YYYY-MM-DD |
occupancy |
yes | One entry per room: adults, and children as a list of ages |
locations, properties, country_codes |
no | Narrow the search |
The answer has three parts:
id: the search id, which you need to book.expires: a Unix timestamp thirty minutes after the search. After it the search id is refused, and you search again.properties: what can be sold for that stay and party, as property → room → rate plan. Under each rate plan is a list ofprices, one for each way of placing the party in the room. Each price has:id: the accommodation id, which you book with;description: a placeholder today ("[to-do]"), do not show it;priceanddiscount_percent, andold_priceonly when there is a discount;availability: how many of this room are left;free_children_ages, only when the hotel accommodates young children free of charge: the ages of the children in your party whom this price leaves out. They stay in the booking as guests; book with the same party.
Only rate plans with booking_types.search are returned, because only
those can be booked this way.
POST /booking
{
"search_id": "…",
"property": 1860,
"ref_id": "AG-2026-00417",
"checkin_date": "2026-07-14",
"checkout_date": "2026-07-21",
"client": {
"first_name": "Ivan",
"last_name": "Petrov",
"email": "[email protected]",
"phone": "+359888123456"
},
"notes": "Late arrival",
"items": [
{
"ref_id": "AG-2026-00417-1",
"room": 5696,
"rate": 11058,
"accommodation_id": "…",
"extra_services": [ { "id": 412, "qty": 1 } ],
"guests": [
{ "first_name": "Ivan", "last_name": "Petrov", "adult": true },
{ "first_name": "Nikola", "last_name": "Petrov", "adult": false, "non_adult_age": 7 }
]
}
]
}
| Field | Required | |
|---|---|---|
search_id |
yes | From the search, within its thirty minutes |
property |
yes | One booking is for one property |
checkin_date, checkout_date |
yes | The dates you searched for |
client |
yes | first_name, last_name, email, phone; optionally nationality, i_want_invoice, booking_for_someone_else, and company (name, address, reg_no, vat_no, rp_name) for an invoice |
items |
yes | One per room: room, rate and accommodation_id |
items[].extra_services |
no | Extras that were in the offer you searched, as id and qty (at least 1) |
items[].beds_preferences |
no | Accepted, but not stored today |
items[].guests |
no | Names, and the age of each child (non_adult_age) |
ref_id, items[].ref_id |
no | Your own ids for the booking and for each room |
booking_timestamp |
no | Accepted, but not stored today: the booking's booking_dt_unix is when we created it |
A field that is not in this table is refused with error 4.
The answer is the booking, in the shape GET /booking
returns. This call takes no locale, so its texts (hotel, room and policy
names) come in the hotel's own language; read the booking with
GET /booking?locale=… for yours. Its booking_status tells you where it
stands:
CREATED: confirmed.POST /bookingalways books instantly, whatever the property'sbooking_type.
A booking that waits for the hotel (REQUESTED, then APPROVED or
CANCELLED, with a webhook for each) is made through
request-with-price or request-auto-price,
or through with-price and auto-price on a property that confirms bookings
itself (booking_type: request).
Rules worth knowing
- Send your
ref_id. While a booking with thatref_idis live (not cancelled), another booking call with it is refused as a duplicate (error 13), so a retry after a timeout does not book the room twice. You can also read, change and cancel a booking by itsref_id. Roomref_ids are stored but not checked for duplicates. - Book what you searched for. The dates must be the search's dates (otherwise error 5), and the accommodation must be one the search offered for that room and rate plan (otherwise error 10). The price is sealed inside the search id and is the price you book. If the hotel's own price for the stay has moved by more than 10 EUR since your search, the booking is refused with error 6: search again.
- A booking is all of its rooms or none. If one item fails, nothing is created.
- The hotel's occupancy rules apply. The number of guests comes from the
offer, the children's ages from
guests, in order. A party the room cannot take with those ages is refused with error 10, and the message says why (see Errors). - No more guests than the offer was priced for.
guestsmay name fewer people than the offer (the rest are filled in), but more is refused with error 6: "Item #1: 3 guests for an offer priced for 2!". Search again with the larger party.
Need the price of one stay without showing a list first? See Book at our price. Selling at a price you contracted with the hotel? See Book with your price.