Overview

The Retrieve Unit Images endpoint allows an Agent to retrieve image assets associated with units in their accessible Inventory, either in bulk or for a specific unit.

This endpoint returns listing-level image content configured and published by the supplier in the CiiRUS system. Image assets typically include property photos used for guest-facing galleries and listing detail pages.

This data is commonly used for:

Rendering property image galleries and carousels
Supporting listing detail and preview experiences
Aligning visual presentation across suppliers and distribution channels

Returned results may vary based on supplier configuration, publication status, and (when specified) channel context.

Related Supplier Configuration (Optional Context)

The image data returned by this endpoint reflects listing images configured and managed by the supplier in the CiiRUS system.

Listing images and gallery configuration
- Add & configure listing images

Endpoints Available

Method	Endpoint	Description
GET	v2024.07.31/unit_images	Returns image assets for units in the inventory.
GET	v2024.07.31/unit_images/{unit_id}	Returns image assets for a specified unit in the inventory.

Path Parameters

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

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 that have been modified after the specified date.	date-time
last_reservation_update_date	Optional	Only return units that have received a booking (their own or a calendar sync) after the specified date.	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 Unit in Inventory	int
unit_ids	Optional	Unique Identifier for Units in Inventory	array
management_company_user_id	Optional	Unique Identifier for Supplier	int
management_company_user_ids	Optional	Unique Identifiers for Suppliers	array
enabled	Optional	Use only 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 the management company's website.	boolean
allocation_on_arrival	Optional	Return the allocation on arrival object.	boolean
allocation_on_arrival_unit	Optional	Return units that are the representative unit in their group.	boolean
channel	Optional	Restrict results to a specific channel’s configuration context. Leave empty for the default/general image set.	string
listing_id	Optional	Lookup a unit by its channel-specific listing ID.	string

Allowed values for channel:

all
bdc
vrbo
airbnb

Channel Context (Optional)

The channel parameter exists to return image sets aligned to a specific distribution channel’s requirements and supported configuration.

For most API partners, the recommended behavior is to omit the channel parameter and rely on the default image set configured for the unit.

When channel is provided:

The image set returned may differ in size, ordering, or availability
Channel-specific publication rules may apply
Not all images configured at the supplier level may be eligible for all channels

Channel-scoped image retrieval is primarily intended for internal CiiRUS integrations to mirror OTA-level listing presentation and validate channel readiness.

Response Definition

Response Item	Description	Data Type
`"unit_images"`	An array containing information about different units. Each element in the array represents unique unit details associated with the unit's images.	array

`"unit_images"` Object

Response Item	Description	Data Type
`"unit_id"`	The unique identifier of the unit these images belong to. This matches the `"unit_id"` used across downstream endpoints such as `/unit_calendars`, `/unit_quotes`, and `/reservations`.	int
`"management_company_user_id"`	The unique identifier of the supplier (management company) that manages the unit. This maps directly to the supplier `"id"` returned by `/suppliers` and is commonly used for supplier-scoped grouping and synchronization logic.	int
`"images"`	An ordered array of image objects representing the visual assets configured for the unit. Images are returned in display order and reflect supplier-defined gallery configuration.	array
`"error"` (Optional)	When present, indicates the unit is returned in the result set but is not fully actionable under the current integration context (for example, supplier-restricted access). The error message should be treated as informational and used to exclude the unit from downstream operational workflows as appropriate.	object

`"images"` Object

Response Item	Description	Data Type
`"id"`	The unique identifier assigned to the image asset within the CiiRUS system. This identifier is stable and may be used for internal reference, caching strategies, or reconciliation of image updates over time.	int
`"sort_order"`	The supplier-defined display order of the image within the unit’s image gallery. Lower values indicate higher priority placement. Partners should respect this ordering when rendering galleries, carousels, or featured images.	int
`"resource"`	A fully qualified URL pointing to the image asset hosted by CiiRUS. This URL may be used directly in client applications, websites, or channel integrations to render the image.	string
`"tag"`	A caption or descriptive label associated with the image. This value is typically used by suppliers to provide context (for example, “Pool Area”, “Master Bedroom”, “Living Room”). If no custom caption has been configured, this field defaults to the original uploaded image filename. Partners should treat this field as descriptive metadata, not a structured classification.	string

`"error"` Object

Response Item	Description	Data Type
`"message"`	When present, indicates the unit is returned in the result set but is not fully actionable under the current integration context (for example, supplier-restricted access). The error message should be treated as informational and used to exclude the unit from downstream operational workflows as appropriate.	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

🚧
If image data is missing or incomplete, this does not automatically indicate a technical error or API issue. Images are configured and managed by the Property Manager within CiiRUS.
If the supplier confirms that images are properly configured and published but the API response still appears incomplete or incorrect, please contact CiiRUS API Support with the affected unit_id, channel (if applicable), and a brief description of the discrepancy.

Sample Request

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

Sample Response

{
    "unit_images": [
        {
            "unit_id": 219264,
            "management_company_user_id": 42330,
            "images": [
                {
                    "id": 1413701,
                    "sort_order": 2,
                    "resource": "https://cdn.ciirus.com/properties/42334/219264/images/download(2).jpg",
                    "tag": "download(2)"
                },
                {
                    "id": 1413702,
                    "sort_order": 3,
                    "resource": "https://cdn.ciirus.com/properties/42334/219264/images/download.jpg",
                    "tag": "download"
                },
                {
                    "id": 1413703,
                    "sort_order": 4,
                    "resource": "https://cdn.ciirus.com/properties/42334/219264/images/images(1).jpg",
                    "tag": "images(1)"
                },
                ...
                ...
                      {
            "unit_id": 222003,
            "management_company_user_id": 42330,
            "images": [
                {
                    "id": 1413735,
                    "sort_order": 1,
                    "resource": "https://cdn.ciirus.com/properties/37284/217105/images/download.jpg",
                    "tag": "download"
                },
                {
                    "id": 1413736,
                    "sort_order": 2,
                    "resource": "https://cdn.ciirus.com/properties/37284/217105/images/images(1).jpg",
                    "tag": "images(1)"
                },
                {
                    "id": 1413738,
                    "sort_order": 3,
                    "resource": "https://cdn.ciirus.com/properties/37284/217105/images/images.jpg",
                    "tag": "images"
                }
            ],
            "error": {
                "message": "Property has been deleted."
            }
        },
            ]
        },
    ],
     "paging": {
        "next_page_url": "https://api.ciiruspartners.com/v2024.07.31/unit_images?page=2&page_size=25",
        "total_page_count": 13,
        "page": 1,
        "page_size": 25
    }
}

Overview

Related Supplier Configuration (Optional Context)

Endpoints Available

Path Parameters

Query String Parameters

Channel Context (Optional)

Response Definition

"unit_images" Object

"images" Object

"error" Object

"paging" Object

Sample Request

Sample Response

`"unit_images"` Object

`"images"` Object

`"error"` Object

`"paging"` Object