API Reference

V3.1 - Multi Units

Context

Hostfully PMP has recently introduced BETA of Multi-Units feature. Due to its nature, that feature introduces global, sometimes breaking, changes to our APIs.

What is Multi-Units

The Multi-Unit Inventory Management feature in the Hostfully Property Management Platform is designed to streamline the management of properties with multiple units, such as apartment buildings, hotels, or vacation rental complexes. This new product allows property managers to treat multiple similar units under a single listing, simplifying bookings, inventory tracking, and availability management. Instead of managing each unit separately, property managers can group them, making it easier to handle high-volume bookings, maintain accurate inventory counts, and ensure better guest management. This feature enhances operational efficiency, reduces manual workload, and provides more flexibility for scaling property portfolios.

What are the changes to the API?

  1. New URI version https://sandbox-api.hostfully.com/api/v3.1/*
  2. Some endpoints had their model updated:
    1. https://sandbox-api.hostfully.com/api/v3.1/jobs
    2. https://sandbox-api.hostfully.com/api/v3.1/custom-data
    3. https://sandbox-api.hostfully.com/api/v3.1/pin-codes
    4. https://sandbox-api.hostfully.com/api/v3.1/leads
  3. Some new endpoints
    1. https://sandbox-api.hostfully.com/api/v3.1/multi-units/hotels
    2. https://sandbox-api.hostfully.com/api/v3.1/multi-units/unit-types
    3. https://sandbox-api.hostfully.com/api/v3.1/multi-units/units
  4. Implicit model changes. See below

What are the implicit model changes to the API?

Hostfully API model of inventory

We've broken down what previously was a Property into 3 resources: Hotel, UnitType and Unit.

  • Hotel aggregates unit types and also centralises some of the shared data - like f.ex. building amenities, photos and address.
  • Unit is just a bookable instance
  • Unit Type describes the rest, meaning:
    • pricing
    • availability
    • channel settings
    • unit type level photos
    • descriptions

Effect on 3.0 endpoints that had not had their model updated

Considering above, for the most part, unit type can be treated as a property. That means that related resources that have not gotten a dedicated 3.1 version can be managed by passing unitType.uid as propertyUid without any domain changes. That's true for example for:

  1. pricing periods
  2. photos
  3. channel links
  4. amenities
  5. descriptions
  6. rooms
  7. tags

Effect on 3.1 endpoints that had their model updated

As for the resources that have gotten their dedicated 3.1 version

  1. Leads are accepting propertyUid field, but in case given uid represents a unit type, then lead will be created for multi-unit inventory, and unit will be automatically selected.
    1. API Client can specify a unitUid, but Hostfully PMP can rearrange lead allocation in order to maximize occupancy
  2. Jobs, Pin Codes and Custom Data will accept unitType.uid as propertyUid, but in case propertyUid holds a unitType.uid, then unitUid presence and validity will be checked.