Overview

A Multi-room or Group Booking allows a user to reserve multiple rooms within the same property under a single reservation

Useful for:

Families booking several rooms together
Groups traveling for events or business trips
Hotels managing reservations across different unit types

The functionality is supported through Hostfully’s Public API, enabling developers to create and manage multi-room bookings programmatically.

Supported Property Types

Multi-room reservations can be created for Multi-unit properties of types:

Master/Sub properties
- Multiple units can be booked in the same property under one reservation.
Multi-Unit Property
- Designed for hotels or complexes with unit-types and respective units.
- Supports booking different unit types across the same property.

Structure

A group booking is structured with one main lead and multiple sub-leads:

Main Lead
- Represents the overall group booking.
- Used for indexing, grouping, and reporting.
Sub-Leads
- Represent individual rooms within the booking.
- Contain the actual reservation data (dates, guests, unit type, etc.).

Using the V3.3 Leads API for Group bookings

The Leads API (v3.3) introduces support for reading group bookings in a dedicated endpoint

Meaning of fields dependning on use case

For Multi-Unit

Field	Main Lead	Sub-Leads
`hotelUid`	Multi-Unit Property UID	Multi-Unit Property UID
`unitUid`	`null`	UID of the booked unit
`propertyUid`	Multi-Unit Property UID	UID of the unit type

For Master/Sub Properties

Field	Main Lead	Sub-Leads
`hotelUid`	`null`	`null`
`unitUid`	`null`	`null`
`propertyUid`	Master property UID	Sub-unit UID

Common Fields (Main Lead & Sub-Leads)

Field	Description
`groupUid`	Shared unique UID across the group booking, auto-generated after creation

Updating leads

PATCH-/api/v3.3/leads/{leadUid}

The Leads API does not allow updating an entire group booking in a single request. Instead, you must update each lead individually (main lead or sub-lead).

Main Lead

Only guest details can be updated on the main lead.

The phone number and contact email provided will automatically propagate to all sub-leads.

Sub-Leads

Allow updating the reservation-specific details.

The following fields can be updated:

{  
    "guestInformation": {  
        "firstName": "Guest name",  
        "lastName": "Last Name",  
        "countryCode": "US",  
        "email": "[email protected]",  
        "secondaryEmail": "",  
        "phoneNumber": "",  
        "cellPhoneNumber": ""  
    }  
}

{  
    "propertyUid": "UID of subUnit or unitType",  
    "unitUid": "UID of unit in case Hotel",  
    "guestInformation": {  
        "firstName": "Guest first name",  
        "adultCount": 1,  
        "childrenCount": 0,  
        "petCount": 0,  
        "infantCount": 0,  
        "email": "[email protected]"  
    },  
    "checkInLocalDate": "2025-02-01",  
    "checkOutLocalDate": "2025-02-10"  
}

Data Propagation Rules on Update

When updating sub-leads, certain data automatically propagates back to the main lead:

Check-in and check-out range - The main lead will reflect the earliest check-in and latest check-out across all sub-leads.
Guest counts - Total from all sub-leads are aggregated at the main lead level.

Upgrading to Subsequent Versions

Please refer to this guide for API migration.