Overview

The Retrieve Reviews endpoint returns guest review records for units in the CiiRUS inventory. Reviews are most commonly consumed for website/marketing use cases, partner-facing dashboards, and operational reporting, but they can also be used to support customer service workflows (for example, validating recurring issues a guest mentions across stays).

This endpoint is designed to be flexible: you can pull reviews broadly, filter by unit(s) or supplier(s), or target specific review IDs or reservation IDs. You can also filter by the date the review was submitted and by arrival/departure windows of the underlying reservation (where applicable), which is helpful for incremental sync jobs..

📘
Important implementation notes:

Reviews may be returned in a “published” or “unpublished” state depending on supplier workflow. If your product displays reviews publicly, you should only display reviews where "published": true, and "status": "approved",).

Some suppliers allow anonymous reviews. In those cases, where "anonymous": true, personally identifying fields may be blank or intentionally generic.

Related Supplier Configuration (Optional Context)

Reviews returned by this endpoint are influenced by how the supplier manages and publishes reviews inside CiiRUS, including whether reviews are enabled for website display and how/when they are published.

Website review configuration and publishing behavior
- Website reviews

Available Endpoints

Method	Endpoint	Description
GET	v2024.07.31/reviews	Retrieve all reviews available in the system.
GET	v2024.07.31/reviews/{review_id}	Retrieve a specific review by its unique identifier.

Path Parameters

Path Parameter	Required / Optional	Description
{review_id}	Required	Unique identifier for a review.

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
no_total	Optional	Removes the total page count for faster results (defaults to false).	boolean
last_update_date	Optional	Only return reviews that have been modified after the specified timestamp. Useful for incremental sync jobs.	date-time
unit_id	Optional	The unique identifier for a specific unit in the inventory.	int
unit_ids	Optional	The unique identifiers for multiple units in the inventory.	array[ints]
management_company_user_id	Optional	The unique identifier for a specific supplier of units.	int
management_company_user_ids	Optional	The unique identifiers for multiple suppliers of units.	array[ints]
review_id	Optional	The unique identifier for a specific review.	int
review_ids	Optional	The unique identifiers for multiple reviews.	array
reservation_id	Optional	The unique identifier for a specific reservation.	int
reservation_ids	Optional	The unique identifiers for multiple reservations.	array[ints]
review_start	Optional	Only return reviews that were created after the specified date and time.	date-time
review_end	Optional	Only return reviews that were made before the specified date and time.	date-time
arrival_start	Optional	Only return reviews whose reservation arrival date/time is after this timestamp.	date-time
arrival_end	Optional	Only return reviews whose reservation arrival date/time is before this timestamp.	date-time
departure_start	Optional	Only return reviews whose reservation departure date/time is before this timestamp.	date-time
departure_end	Optional	Only return reviews whose reservation departure date/time is before this timestamp.	date-time

Response Definitions

Response Item	Description	Data Type
`"reviews"`	An array of review records returned by the request. Each object represents a single guest review associated with a unit. Reviews may be published or unpublished, anonymous or attributed, and may reflect different moderation states depending on supplier configuration.	array
`"paging"`	Paging metadata used to navigate through large result sets when multiple reviews are returned.	object

`"reviews"` Object

Response Item	Description	Data Type
`"id"`	The unique identifier for the review record. This value represents the authoritative identity of a guest review within CiiRUS. Integrating partners should use this field as the primary key when storing reviews, synchronizing updates, associating reviews with units or reservations, and preventing duplicate records in downstream systems.	int
`"management_company_user_id"`	The unique identifier of the management company (supplier) that manages the unit associated with this review. This value can be used to scope reviews to a specific supplier when aggregating or filtering data across multiple management companies.	int
`"review_date"`	The calendar date on which the guest submitted the review. This value reflects when feedback was recorded, not when the stay occurred. Integrating partners commonly use this field for chronological sorting, recency filters, and review freshness indicators.The date the review was submitted by the guest. This represents the guest’s submission date, not the arrival or departure date of the stay.	date
`"rating"`	The numeric score assigned by the guest to their stay. This value should always be interpreted in conjunction with `"rating_scale"` to determine its relative meaning (for example, `4.0` out of `5.0`).	float
`"rating_scale"`	Defines the maximum possible rating value for the review. This enables partners to normalize ratings across different scales (e.g., 5-point vs 10-point systems) when aggregating or displaying reviews.	float
`"anonymous"`	Indicates whether the guest elected to submit the review anonymously. When `true`, personally identifiable reviewer information (such as name or email) may be masked, omitted, or intentionally generic.	boolean
`"name"`	The reviewer’s display name as provided at submission time. This may represent a full name, partial name, or alias depending on guest preference and anonymity settings.	string
`"emails"`	The email address associated with the reviewer at the time of submission, if available and permitted. This field should not be relied upon as a guaranteed contact method and may be empty for anonymous reviews.	string
`"published"`	Indicates whether the review is approved and publicly visible (for example, on a website or listing page). Reviews marked as unpublished may still exist for moderation, internal review, or administrative purposes.	boolean
`"content"`	An array containing one or more content objects that together represent the body of the review. While most reviews currently contain a single entry, partners should not assume this will always be the case and should iterate over the array when processing or displaying review content.	array
`"reviewer"`	Identifies the role or source of the review submission. Typical values include `"GUEST"`, indicating the review was submitted by a guest following a completed stay.	string
`"status"`	Represents the moderation or lifecycle state of the review. This value determines whether the review is eligible for publication and may reflect internal approval workflows.	string
`"unit_id"`	The unique identifier for the unit. This value maps directly to `"unit_id"` returned by the `/units` endpoint and is used to correlate inventory records across downstream workflows.	int
`"ready_only"`	Indicates whether the review record is immutable. When true, the review cannot be edited or altered through the API or management interfaces and should be treated as finalized content.	boolean

🚧
Important Note:
Under certain conditions, duplicate review records with the same "id" may be returned in a single response. Integrating partners should de-duplicate reviews using the "id" field. This behavior is under review.

`"content"` Object

Response Item	Description	Data Type
`"value"`	The actual written review text submitted by the guest. This field contains free-form, user-generated content and may include punctuation, line breaks, or extended narrative text. Partners should treat this value as display-ready but should still apply standard sanitation or encoding practices when rendering in UIs.	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/reviews?page=1&page_size=25&no_total=false' \
--header 'Authorization: Basic {APIUsername:APIPassword}'

Sample Response

{
    "reviews": [
        {
            "id": 30768,
            "management_company_user_id": 0,
            "review_date": "2019-08-29",
            "rating": 5.0,
            "rating_scale": 5.0,
            "anonymous": false,
            "name": "Guest Name",
            "emails": "[email protected]",
            "published": false,
            "content": [
                {
                    "value": "Test Review"
                }
            ],
            "reviewer": "GUEST",
            "status": "not_approved",
            "unit_id": 226596,
            "read_only": true
        },
        {
            "id": 58219,
            "management_company_user_id": 0,
            "review_date": "2021-10-06",
            "rating": 4.0,
            "rating_scale": 4.0,
            "anonymous": false,
            "name": "Sample Test",
            "emails": "[email protected]",
            "published": true,
            "content": [
                {
                    "value": "Wonderful property and great customer service provided by host.  Location was superb."
                }
            ],
            "reviewer": "GUEST",
            "status": "approved",
            "unit_id": 265308,
            "read_only": true
        },
        {
            "id": 3,
            "management_company_user_id": 0,
            "review_date": "2011-12-29",
            "rating": 4.0,
            "rating_scale": 4.0,
            "anonymous": false,
            "name": "John Johnson",
            "emails": "",
            "published": true,
            "content": [
                {
                    "value": "Lovely place.\r\nWe all realy enjoyed the facilities and the fact it was so close to all the theme parks.\r\nThe management company were really helpful and met all our expectations."
                }
            ],
            "reviewer": "GUEST",
            "status": "approved",
            "unit_id": 41123,
            "read_only": true
        },..
    ],
    "paging": {
        "next_page_url": "https://api.ciiruspartners.com/v2024.07.31/reviews?page=2&page_size=25&no_total=false",
        "total_page_count": 3,
        "page": 1,
        "page_size": 25
    }
}

Overview

Important implementation notes:

Related Supplier Configuration (Optional Context)

Available Endpoints

Path Parameters

Query String Parameters

Response Definitions

"reviews" Object

Important Note:

"content" Object

"paging" Object

Sample Request

Sample Response

`"reviews"` Object

`"content"` Object

`"paging"` Object