Overview

The Retrieve Unit Calendars endpoint returns availability and stay-rule data for one or more units over a defined date range. This includes daily availability status, arrival and departure restrictions, minimum and maximum stay rules, and allocation-on-arrival behavior where applicable.

This endpoint is commonly used to power availability searches, calendar views, and pre-booking validation logic prior to quoting or reservation creation.

Calendar results reflect a combination of supplier configuration, reservation activity (including synced reservations), and channel-specific rules when requested.

Related Supplier Configuration (Optional Context)

Availability and calendar behavior returned by this endpoint is influenced by reservation and calendar configuration within the CiiRUS system, including supplier-defined restrictions and reservation activity.

Default arrival and departure behavior
- Setting default check-in/out times
Reservation rules and behavior
- Configuring general reservation settings
- Add a blackout date
Reservation activity impacting availability
- Add a new reservation
- Cancel a reservation

Endpoints Available

Method	Endpoint	Description
GET	v2024.07.31/unit_calendars	Returns availability calendar and configuration for units in inventory.
GET	v2024.07.31/unit_calendars/{unit_id}	Returns the availability calendar and configuration for a specific unit.

Path Parameters

Path Parameter	Required / Optional	Description
{unit_id}	Required	Unique identifier for the unit.

Query String Parameters

Parameter	Required / Optional	Description	Data Type
page	Optional	The page number to display (default: 1).	int
page_size	Optional	Limits the number of returned results (default: 25).	int
last_unit_update_date	Optional	Returns units modified after the specified date.	date-time
last_reservation_update_date	Optional	Returns units that have received a booking or calendar sync after the specified date.	date-time
last_agent_module_property_update_date	Optional	Returns units with modified agent module property configuration after the specified date.	date-time
last_agent_module_agent_update_date	Optional	Returns units with modified agent module agent configuration after the specified date.	date-time
unit_id	Optional	Filter results to a specific unit ID.	int
unit_ids	Optional	Filter results to multiple unit IDs.	array[int]
management_company_user_id	Optional	Filter results to a specific supplier.	int
management_company_user_ids	Optional	Filter results to multiple suppliers.	array[int]
enabled	Optional	Return only enabled or disabled units.	boolean
deleted	Optional	Return only deleted or non-deleted units.	boolean
display_on_website	Optional	Return only units enabled for the website.	boolean
allocation_on_arrival	Optional	Include allocation-on-arrival availability data where applicable.	boolean
allocation_on_arrival_unit	Optional	Return only representative units within allocation-on-arrival groups.	boolean
start	Required	Start date for retrieving calendar availability.	date
end	Required	End date for retrieving calendar availability.	date
reservation_id	Optional	Reservation ID used to evaluate availability in the context of a modification.	int
allocated_reservations	Optional	List of unallocated reservation IDs to virtually allocate for availability checks.	array[int]
category_to_ignore	Optional	Booking category to ignore when calculating availability.	boolean
fallback_rates	Optional	Determines fallback behavior when nightly rates are missing. Defaults to `fallback_max_value_rate_plus_guards`.	string (enum)
channel	Optional	Restrict results to a specific channel’s configuration context. Leave empty for the default/general data.	string (enum)
listing_id	Optional	Lookup a unit by its channel-specific listing ID.	string

Allowed values for fallback_rates:
- explicitly_in_date_range_only
- fallback_max_value_rate
- fallback_max_value_rate_plus_guards
Allowed values for channel:
- all
- bdc
- vrbo
- airbnb

Response Definition

Response Item	Description	Data Type
`"unit_calendars"`	Collection of calendar records, each representing availability, stay rules, and booking constraints for a specific unit over the requested date range.	array
`"paging"`	Metadata used to paginate multi-unit calendar results when querying large inventories.	object

`"unit_calendars"` Object

Response Item	Description	Data Type
`"unit_id"`	Unique identifier for the unit whose availability calendar is being returned. This value maps directly to the unit inventory record.	int
`"management_company_user_id"`	Unique identifier for the supplier (property manager) that owns or manages the unit.	int
`"start_date"`	The effective start date and time of the calendar range returned for this unit, based on the request parameters.	date-time
`"end_date"`	The effective end date and time of the calendar range returned for this unit, based on the request parameters.	date-time
`"days"`	Array of day-level availability records, including booking restrictions, arrival/departure rules, and stay length constraints for each date.	array
`"allocation_on_arrival"`	Allocation-on-arrival configuration for grouped units, indicating how availability is managed when multiple similar units share inventory. Returned only when applicable or explicitly requested.	object
`"error"`	Error details returned when availability data cannot be generated for this unit (for example, missing configuration or invalid parameters).	object

`"days"` Object

Response Item	Description	Data Type
`"date"`	Calendar date this availability record applies to.	date
`"availability"`	Overall availability state for the unit on this date (e.g., `available` or `unavailable`). This is the primary indicator used for booking eligibility.	string
`"availability_type"`	Describes why the unit is available or unavailable for the given date. This value is primarily intended for diagnostics, reporting, and explaining availability behavior in partner-facing UIs. Refer to Valid `"availability_type` values for a complete list.	string
`"closed_to_arrival"`	Indicates whether new reservations are prohibited from starting on this date, even if the unit is otherwise available.	boolean
`"closed_to_departure"`	Indicates whether reservations are prohibited from ending on this date.	boolean
`"minimum_nights"`	Minimum number of nights a reservation must span if it begins on this date.	int
`"maximum_nights"`	Maximum number of nights a reservation may span if it begins on this date.	int
`"settings"`	Detailed stay rules and constraints applied to this date, including booking fences and allowed arrival/departure days.	object
`"stay_durations"`	Explicit list of allowed stay lengths (in nights) for reservations starting on this date.	array[int]

`"settings"` Object

Response Item	Description	Data Type
`"booking_fence"`	Minimum number of days in advance a reservation must be made for this date. A value of `0` indicates same-day booking is allowed.	int
`"gap_days"`	Required minimum number of vacant days between adjacent reservations. Used to enforce cleaning or operational buffers.	int
`"minimum_nights"`	Minimum stay length permitted for reservations starting on this date, after applying all rules.	int
`"maximum_nights"`	Maximum stay length permitted for reservations starting on this date.	int
`"arrival_days"`	List of weekdays on which guests are allowed to check in for this unit.	array[string]
`"departure_days"`	List of weekdays on which guests are allowed to check out for this unit.	_array[string]

`"stay_durations"` Array

Response Item	Description	Data Type
(value)	Allowed length of stay, expressed in number of nights, for reservations beginning on the associated date.	int

`"allocation_on_arrival"` Object

Response Item	Description	Data Type
`"availability"`	Availability state of the allocation group rather than an individual unit.	string
`"available_unit_count"`	Number of units currently available within the allocation group for the requested date range.available_unit_count	string
`"change_over"`	Changeover rule applied at the allocation level (e.g., same-day turns or fixed turnovers).	string
`"max_stay"`	Maximum stay length permitted when allocating from the group.	string
`"min_prior_notify"`	Minimum number of days’ notice required before arrival when booking within the allocation group.	string
`"min_stay"`	Minimum stay length enforced across the allocation group.	string
`"stay_increment"`	Required increment (in nights) for valid stay lengths within the allocation group.	string

`"error"` Object

Response Item	Description	Data Type
`"message"`	Human-readable explanation describing why calendar data could not be returned for this unit.	string

`"paging"` Object

Response Item	Description	Data Type
`"total_page_count"`	Total number of pages available for the current query.	int
`"page"`	Current page number being returned.	int
`"page_size"`	Number of records returned per page.	int
`"next_page_url"`	URL to request the next page of results, if additional pages exist.	string
`"previous_page_url"`	URL to request the previous page of results, when applicable.	string

Sample Request

curl --location 'https://api.ciiruspartners.com/v2024.07.31/unit_calendars?page=1&page_size=25&enabled=true&start=2025-03-04&end=2026-03-03' \
--header 'Content-Type: application/json' \
--header 'authorization: Basic {APIUsername:APIPassword}'

Sample Response

{
    "unit_calendars": [
        {
            "unit_id": 104798,
            "management_company_user_id": 11006,
            "start_date": "2025-03-04T17:00:00",
            "end_date": "2026-03-03T12:00:00",
            "days": [
                {
                    "date": "2025-03-04",
                    "availability": "available",
                    "availability_type": "available",
                    "closed_to_arrival": false,
                    "closed_to_departure": false,
                    "minimum_nights": 2,
                    "maximum_nights": 1763,
                    "settings": {
                        "booking_fence": 0,
                        "gap_days": 0,
                        "minimum_nights": 2,
                        "maximum_nights": 1763,
                        "arrival_days": [
                            "monday",
                            "tuesday",
                            "wednesday",
                            "thursday",
                            "friday",
                            "saturday",
                            "sunday"
                        ],
                        "departure_days": [
                            "monday",
                            "tuesday",
                            "wednesday",
                            "thursday",
                            "friday",
                            "saturday",
                            "sunday"
                        ]
                    },
                    "stay_durations": [
                        2,
                        3,
                        4,
                        5,
                        6,
                        7,
                        8,
                        9,
                        10,
                        ...
                    ]
                },
                 {
            "unit_id": 0,
            "management_company_user_id": 0,
            "start_date": "0001-01-01T00:00:00",
            "end_date": "0001-01-01T00:00:00",
            "error": {
                "message": "{\"message\":\"Unit quote options could not be found.\"}"
            }
        }
    ],
    "paging": {
        "next_page_url": "https://api.ciiruspartners.com/v2024.07.31/unit_calendars?page=2&page_size=25&enabled=true&start=2025-03-04&end=2026-03-03",
        "total_page_count": 3,
        "page": 1,
        "page_size": 25
    }
}

Overview

Related Supplier Configuration (Optional Context)

Endpoints Available

Path Parameters

Query String Parameters

Response Definition

"unit_calendars" Object

"days" Object

"settings" Object

"stay_durations" Array

"allocation_on_arrival" Object

"error" Object

"paging" Object