Overview

The Retrieve Units endpoint represents the next step in the standard CiiRUS Partner API integration workflow after an Agent has identified their connected suppliers via /suppliers. It allows an Agent to retrieve the inventory units that are available within their integration scope and establish the foundational unit context used throughout the remainder of the integration.

This endpoint is commonly used to:

Build and persist a local mapping of "unit_id" values used across downstream endpoints such as /unit_calendars, /unit_quotes, and /reservations.
Group inventory by supplier using "management_company_user_id", which maps directly to the supplier "id" returned by /suppliers, enabling supplier-scoped synchronization and operational logic.
Surface unit-level metadata required for internal property selection and operational logic, including internal unit identifiers, bedroom and bathroom counts, community affiliation, timezone, and address details (when populated).
Support incremental inventory synchronization by filtering units based on timestamp fields such as "last_unit_update_date".

📘
Important Note: Unit Actionability & Enablement
A unit may be returned by this endpoint even if it is not currently actionable for booking or synchronization.
The "enabled" flag represents the unit’s effective enablement state for the current integration context. A unit is only considered enabled when both of the following are true:

"agent_enabled" = true — the Agent has enabled the unit for their integration

"supplier_enabled" = true — the supplier has enabled the unit for agent connections

If either value is false, "enabled" will be returned as false, and the unit must be treated as out of scope for downstream workflows such as availability (/unit_calendars), pricing (/unit_quotes), and booking (/reservations).
Agents should only attempt to enable units where "supplier_enabled" is true.
When "supplier_enabled" is false, the supplier has explicitly restricted agent access to that unit. In this state:

The Agent should not enable the unit via the Update Units endpoint.

"enabled" will remain false regardless of the Agent’s actions.

The unit should be treated as out of scope for availability, pricing, and booking workflows.

Supplier-controlled restrictions cannot be overridden by the Agent or by CiiRUS Support.

📘
Naming Clarification:
The "unit_name" value returned by this endpoint represents an internal unit name configured within CiiRUS and should be treated as an internal reference only.
For guest-facing display purposes (for example, listing titles or headlines shown on major OTAs), partners should retrieve and use values returned by the /unit_details endpoint, which exposes the supplier-configured property title and headline used across channel integrations.

Related Supplier Configuration (Optional Context)

Unit Creation and Lifecycle (maps to unit presence, "enabled", "deleted")
- Add a new unit
- Delete a unit
Unit Visibility and Booking Controls (maps to ""online_booking_enabled, "booking_fence", "gap_days")
- Configure online reservation settings
Unit Identity and Structure (maps to "unit_name", "address", "community_id", "bedrooms", "bathrooms")

Endpoints Available

Method	Endpoint	Description
GET	v2024.07.31/units	Retrieve a list of all accessible units.
GET	v2024.07.31/units/{unit_id}	Retrieve a single unit by ID.

Path Parameters

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

Query String Parameters

Parameter	Required / Optional	Description	Data Type
page	Optional	The page to be shown (Defaults to 1).	int
page_size	Optional	Limits the number of returned results (Defaults to 25).	int
last_unit_update_date	Optional	Only return units updated after this timestamp. Use for incremental inventory sync.	date-time
last_reservation_update_date	Optional	Only return units whose reservation-related data was updated after this timestamp. Useful for calendar-driven sync refresh decisions.	date-time
last_agent_module_property_update_date	Optional	Only return units that have had their agent module property configuration modified after the specified date.	date-time
last_agent_module_agent_update_date	Optional	Only return units that have had their agent module agent configuration modified after the specified date.	date-time
unit_id	Optional	Unique identifier for the unit in the inventory.	int
unit_ids	Optional	Unique identifiers for units in the inventory.	array[int]
management_company_user_id	Optional	Unique identifier for the supplier.	int
management_company_user_ids	Optional	Unique identifiers for suppliers.	array[int]
enabled	Optional	Filter results by enabled or disabled units.	boolean
deleted	Optional	Only show properties that are deleted or not deleted.	boolean
display_on_website	Optional	Only show properties that are enabled for website	boolean
allocation_on_arrival	Optional	Return the allocation on arrival object.	boolean
allocation_on_arrival_unit	Optional	Return units that are the representative units in their group.	boolean
channel	Optional	Restrict results to a specific channel’s configuration context.	string
listing_id	Optional	Lookup a unit by its channel-specific listing ID.	string

Allowed values for channel:

all
bdc
vrbo
airbnb

📘
Important Note:
Channel objects (for example, "airbnb" and "vrbo") may not be present unless channel is specified (channel=airbnb, channel=vrbo, or channel=all) and the unit has channel metadata available.

📘
Conditional Response Fields
Some fields are only included in responses when applicable or when their corresponding query filters are used. If a filter is not provided or data is not applicable to a unit, the related fiedls may be ommited from the response.

Response Definition

Response Item	Description	Data Type
`"units"`	A collection of inventory units available within the Agent’s integration scope. Each object represents a single property and its current configuration, status, and eligibility for downstream workflows.A collection of units available within the Agent’s integration scope. Each entry represents a property record accessible via the API.	array[object]
`"paging"`	Paging metadata used to navigate through large result sets when multiple units are returned.	object

`"units"` Object

Response Item	Description	Data Type
`"unit_id"`	The unique identifier for the unit. This value is the primary key used across downstream endpoints such as `/unit_calendars`, `/unit_quotes`, `/unit_details`, and `/reservations`.	int
`"unit_name"`	The internal name of the unit as configured by the supplier. This value is intended for operational identification and should not be treated as a guest-facing display name.The internal name of the unit as configured in CiiRUS.	string
`"master_unit_id"`	If this unit is a clone, this field references the original (master) unit ID. For non-cloned units, this value may be `null` or `0`.	int
`"enabled"`	Indicates whether the unit is enabled for API access within the current Agent’s integration. A value of `false` means the unit should be treated as non-actionable.	boolean
`"native"`	Indicates whether the unit originates directly within the Agent’s system (`true`) or is sourced externally (for example, via a supplier or sync).	boolean
`"agent_enabled"`	Indicates whether the Agent has explicitly enabled this unit within their inventory connection. This flag must be `true` for most booking and sync operations.	boolean
`"supplier_enabled"`	Indicates whether the supplier has allowed agent access to this unit. When `false`, the supplier has explicitly restricted distribution of the unit to agents, and the unit should not be enabled or used in downstream workflows.	boolean
`"clone"`	Indicates whether this unit is a cloned copy of another unit rather than a primary listing.	boolean
`"deleted"`	Indicates whether the unit has been deleted or deactivated by the supplier. Deleted units may still appear for reference but should not be used for booking or sync.	boolean
`"online_booking_enabled"`	Indicates whether online booking is enabled for this unit. If `false`, reservations should not be created through automated or guest-facing flows.	boolean
`"booking_fence"`	The minimum number of days prior to arrival that a reservation must be created. Used to prevent short-notice bookings.	int
`"gap_days"`	The number of required vacant nights enforced between consecutive reservations for this unit.	int
`"include_mandatory_extras"`	Indicates whether mandatory extras (such as required fees or services) are automatically included in pricing and quote responses.	boolean
`"merchant_of_record"`	Identifies which party is responsible for payment processing and financial settlement for this unit. This value influences how payments, refunds, and financial reporting should be handled by the integration. Valid values are documented in the Units enumeration reference. See valid merchant of record values.	string
`"relationship_to_unit"`	Describes the Agent’s relationship to the unit within CiiRUS. This value provides context on how the unit was connected (direct ownership, supersite distribution, calendar sync, etc.) and may influence supported operations and behavior. Valid values are documented in the Units enumeration reference. See valid relationship to unit values.	string
`"timezone"`	The IANA timezone identifier associated with the unit (for example, `"America/New_York"`). Used for arrival, departure, and calendar calculations.	string
`"owner_user_id"`	The unique user ID of the unit’s owner, if applicable.	int
`"owner_name"`	The display name of the unit’s owner, when available.	string
`"management_company_rate_set_id"`	Identifier of the rate set applied by the supplier for pricing calculations.	int
`"management_company_user_id"`	The supplier identifier who manages this unit. This value maps directly to `"id"` returned by `/suppliers`.	int
`"master_owner_user_id"`	The owner user ID associated with the master unit when cloning or inheritance applies.	int
`"master_unit_rate_set_use_nightly_floor_rates"`	Indicates whether nightly floor rate logic is enforced for this unit when calculating pricing.	boolean
`"rent_ready_date"`	The date on which the unit became (or will become) available for rental activity.	date-time
`"community_id"`	Identifier of the community, resort, or grouping the unit belongs to.	int
`"community_name"`	The human-readable name of the community or resort associated with the unit.	string
`"minimum_nights_stay"`	The default minimum number of nights required for a reservation when no more specific rule applies.	int
`"last_unit_update_date"`	Timestamp of the most recent unit-level update in CiiRUS. Commonly used for incremental inventory synchronization.	date-time
`"last_reservation_update_date"`	Timestamp of the most recent reservation-related update associated with this unit.	date-time
`"last_agent_module_agent_update_date"`	Timestamp of the most recent Agent-side configuration change affecting this unit. This field is only returned when the request includes the `last_agent_module_agent_update_date` filter and the unit matches that filter.	date-time
`"last_agent_module_property_update_date"`	Timestamp of the most recent supplier-side configuration change affecting this unit. This field is only returned when the request includes the `last_agent_module_property_update_date` filter and the unit matches that filter.	date-time
`"allocation_on_arrival"`	An object containing allocation-on-arrival configuration for this unit when the unit participates in a representative/category-based allocation workflow. May be omitted when not applicable.	object
`"address"`	An object containing the unit’s address details, when available. Address fields may be returned as empty strings based on supplier configuration and data visibility.	object
`"bedrooms"`	The total number of bedrooms configured for the unit.	int
`"bathrooms"`	The total number of bathrooms configured for the unit. Supports fractional values (for example, `1.5`).	float
`"franchisee"`	The franchisee or internal grouping label associated with the unit, when configured.	string
`"airbnb"`**	Information and settings related to the Airbnb channel connection for this unit (informational only; not required for standard partner workflows).	object
`"vrbo"`**	Information and settings related to the Vrbo channel connection for this unit (informational only; not required for standard partner workflows).	object
`"error"`	An object describing why the unit is not actionable for the current integration context, when applicable. This is not always a technical error.	object

`"allocation_on_arrival"` Object

Response Item	Description	Data Type
`"allocation_on_arrival_unit"`	Indicates whether this unit acts as a representative (model) unit within an allocation-on-arrival category	boolean
`"allocation_on_arrival_unit_id"`	If this unit is representative, it references the unit ID it represents.	int
`"allocation_on_arrival_category"`	Identifier of the allocation category this unit belongs to. Units in the same category may be assigned interchangeably.	int
`"community_id"`	Community identifier associated with the allocation category.	int
`"enforce_allocation_on_arrival_stop_sale"`	If `true`, a stop-sale rule is enforced at the category level. If all units in the same category are unavailable (due to bookings, blocks, etc.), then your system should treat the entire category as unavailable.	boolean

`"address"` Object

Response Item	Description	Data Type
`"address_line_1"`	The primary street address for the unit.	string
`"address_line_2"`	Additional address details such as suite, unit number, or building identifier, if applicable.	string
`"city"`	The city in which the unit is located, when available.	string
`"state_province"`	The state or province in which the unit is located, when available.	string
`"postal_code"`	The postal or ZIP code associated with the unit, when available.	string

📘
Channel Integration Metadata ("airbnb" / "vrbo")
The "airbnb" and "vrbo" objects expose channel-specific metadata used by CiiRUS channel integrations. These fields are informational only for most API partners and are not required for standard inventory, availability, pricing, or reservation workflows. Values and behavior may change as channel integrations evolve.

`"airbnb"` Object

Response Item	Description	Data Type
`"host_id"`	Airbnb host ID associated with the unit.	string
`"listing_id"`	Airbnb listing identifier associated with the unit.	string
`"request_to_book_on_short_notice"`	Indicates whether short-notice bookings are allowed on Airbnb.	boolean
`"short_term_cancelation_policy"`	Short-term cancellation policy configured for the Airbnb listing.	string
`"long_term_cancelation_policy"`	Long-term cancellation policy configured for the Airbnb listing.	string
`"synchronization_category"`	Internal category used to group Airbnb sync behavior.	string
`"publish_listing"`	Indicates whether the Airbnb listing is published.	boolean
`"listing_error_message"`	Optional error or status message related to the Airbnb listing.	string
`"guests_included"`	Number of guests included in the base Airbnb pricing.	int
`"price_per_extra_person"`	Additional per-guest pricing configured for Airbnb.	int
`"allow_length_of_stay"`	Indicates whether length-of-stay rules are applied for Airbnb.	boolean
`"non_refundable_price_factor"`	Price adjustment factor applied to non-refundable Airbnb rates.	decimal

`"vrbo"` Object

Response Item	Description	Data Type
`"sync"`	Indicates whether the unit is configured to sync with Vrbo.	boolean
`"booking_policy"`	Internal Vrbo booking-policy identifier.	int
`"cancellation_policy"`	Internal Vrbo cancellation-policy identifier.	int
`"pricing_mode"`	Internal Vrbo pricing-mode identifier.	int

`"error"` Object

Response Item	Description	Data Type
`"message"`	A message describing why the unit is not actionable for the current integration context (for example, deleted, disabled, or not enabled for this Agent). Partners should treat this as an operational state indicator and reference the Error Manual for cause and resolution guidance.	string

`"paging"` Object

Response Item	Description	Data Type
`"next_page_url"`	A URL that can be used to retrieve the next page of supplier results, if additional pages exist.	string
`"previous_page_url"`	A URL that can be used to retrieve the previous page of supplier results, if applicable.	string
`"total_page_count"`	The total number of available pages for the current request.	int
`"page"`	The current page number being returned.	int
`"page_size"`	The number of records being included per page.	int

Sample Request

curl --location 'https://api.ciiruspartners.com/v2024.07.31/units?page=1&page_size=500&management_company_user_id=42330' \
--header 'Authorization: Basic {APIUsername:APIPassword}'

Sample Response

{
    "units": [
        {
            "unit_id": 219264,
            "unit_name": "Test Property 1",
            "enabled": true,
            "native": false,
            "agent_enabled": true,
            "supplier_enabled": true,
            "clone": false,
            "deleted": false,
            "online_booking_enabled": true,
            "booking_fence": 1,
            "gap_days": 2,
            "include_mandatory_extras": true,
            "merchant_of_record": "management_company",
            "relationship_to_unit": "supersite_agent",
            "timezone": "America/New_York",
            "owner_user_id": 42334,
            "owner_name": "API Owner",
            "management_company_rate_set_id": 235947,
            "management_company_user_id": 42330,
            "master_unit_rate_set_use_nightly_floor_rates": false,
            "rent_ready_date": "2017-01-18T00:00:00",
            "community_id": 17511,
            "community_name": "Encore Resort at Reunion",
            "minimum_nights_stay": 1,
            "last_unit_update_date": "2025-12-01T13:27:34.263",
            "last_reservation_update_date": "2025-12-18T12:00:50.833",
            "address": {
                "address_line_1": "1012 Emmette St",
                "address_line_2": "Suite A",
                "city": "Kissimmee",
                "state_province": "Fl",
                "postal_code": "34741"
            },
            "bedrooms": 0,
            "bathrooms": 2.0,
            "franchisee": "",
            "airbnb": {
                "host_id": "431444876",
                "listing_id": "739807228214052587",
                "request_to_book_on_short_notice": false,
                "short_term_cancelation_policy": "flexible",
                "publish_listing": true,
                "allow_length_of_stay": false,
                "non_refundable_price_factor": 0
            }
        },
        {
            "unit_id": 219265,
            "unit_name": "Test Property 2",
            "enabled": true,
            "native": false,
            "agent_enabled": true,
            "supplier_enabled": true,
            "clone": false,
            "deleted": false,
            "online_booking_enabled": true,
            "booking_fence": 0,
            "gap_days": 0,
            "include_mandatory_extras": false,
            "merchant_of_record": "management_company",
            "relationship_to_unit": "supersite_agent",
            "timezone": "America/New_York",
            "owner_user_id": 42334,
            "owner_name": "API Owner",
            "management_company_rate_set_id": 75114,
            "management_company_user_id": 42330,
            "master_unit_rate_set_use_nightly_floor_rates": false,
            "rent_ready_date": "2017-01-18T00:00:00",
            "community_id": 124,
            "community_name": "Terra Verde Resort",
            "minimum_nights_stay": 2,
            "last_unit_update_date": "2025-11-20T16:55:49.66",
            "last_reservation_update_date": "2025-12-11T09:22:36.307",
            "address": {
                "address_line_1": "1014 Emmette St",
                "address_line_2": "Suite B",
                "city": "Kissimmee",
                "state_province": "Fl",
                "postal_code": "34741"
            },
            "bedrooms": 12,
            "bathrooms": 8.5
        },
        {
            "unit_id": 219266,
            "unit_name": "Test Property 3",
            "enabled": false,
            "native": false,
            "agent_enabled": true,
            "supplier_enabled": false,
            "clone": false,
            "deleted": false,
            "online_booking_enabled": true,
            "booking_fence": 2,
            "gap_days": 0,
            "include_mandatory_extras": true,
            "merchant_of_record": "management_company",
            "relationship_to_unit": "supersite_agent",
            "timezone": "America/New_York",
            "owner_user_id": 42334,
            "owner_name": "API Owner",
            "management_company_rate_set_id": 72025,
            "management_company_user_id": 42330,
            "master_unit_rate_set_use_nightly_floor_rates": false,
            "rent_ready_date": "2017-01-18T00:00:00",
            "community_id": 46,
            "community_name": "Glenbrook",
            "minimum_nights_stay": 2,
            "last_unit_update_date": "2025-11-13T12:44:54.25",
            "last_reservation_update_date": "2025-12-01T12:06:02.237",
            "address": {
                "address_line_1": "1212 Florida Ave",
                "address_line_2": "",
                "city": "Lakeland",
                "state_province": "Fl",
                "postal_code": "33803"
            },
            "bedrooms": 0,
            "bathrooms": 1.0,
            "error": {
                "message": "Property supplier has not enabled this property connection."
            }
        },..
  ],
  "paging": {
    "next_page_url": "https://api.ciiruspartners.com/v2024.07.31/units?page=2&page_size=500&management_company_user_id=42330",
    "total_page_count": 3,
    "page": 1,
    "page_size": 500
  }
}

Overview

Important Note: Unit Actionability & Enablement

Naming Clarification:

Related Supplier Configuration (Optional Context)

Endpoints Available

Path Parameters

Query String Parameters

Important Note:

Conditional Response Fields

Response Definition

"units" Object

"allocation_on_arrival" Object

"address" Object

"airbnb" Object

"vrbo" Object

"error" Object

"paging" Object

Sample Request

Sample Response

`"units"` Object

`"allocation_on_arrival"` Object

`"address"` Object

`"airbnb"` Object

`"vrbo"` Object

`"error"` Object

`"paging"` Object