Overview

The Retrieve Reservations request provides the Agent with a method to access reservation data in the system. By making this API call, the API User can efficiently retrieve and integrate reservation information.

Whether the objective is to retrieve all reservations available to the API user or obtain information about a specific reservation using its unique identifier, this request provides essential reservation details such as reservation dates, guest information, pricing, and more.

Endpoints Available

Method	Endpoint	Description
GET	v2024.07.31/reservations	Retrieves a list of reservations based on query parameters.
GET	v2024.07.31/reservations/{reservation_id}	Fetches details of a single reservation using its unique identifier.

Path Parameters

Path Parameter	Required / Optional	Description
{reservation_id}	Required	The unique identifier for the reservation.

Query String Parameters

Parameter	Required / Optional	Description	Data Type
page	Optional	The page number to retrieve. Defaults to `1`.	int
page_size	Optional	The number of results per page. Defaults to `25`.	int
no_total	Optional	If `true`, removes the total page count for faster results. Defaults to `false`.	boolean
management_company_user_id	Optional	Retrieves reservations for a specific supplier.	int
management_company_user_ids	Optional	Retrieves reservations for multiple suppliers.	array[int]
unit_id	Optional	Retrieves reservations for a specific unit.	int
unit_ids	Optional	Retrieves reservations for multiple units.	array[int]
reservation_id	Optional	Retrieves a specific reservation.	int
reservation_ids	Optional	Retrieves multiple reservations by ID.	array[int]
reference	Optional	Searches by reservation reference.	string
references	Optional	Searches for multiple reservation references.	array[string]
modified_start	Optional	Only return reservations that have been modified after a certain date.	date-time
modified_end	Optional	Only return reservations that have been modified before a certain date.	date-time
arrival_start	Optional	Only return reservations that arrive after a certain date.	date-time
arrival_end	Optional	Only return reservations that arrive before a certain date.	date-time
departure_start	Optional	Only return reservations that depart after a certain date.	date-time
departure_end	Optional	Only return reservations that depart before a certain date.	date-time
cancelled_start	Optional	Only return reservations that have been cancelled after a certain date.	date-time
cancelled_end	Optional	Only return reservations that have been canceled before a certain date.	date-time
added_start	Optional	Only return reservations that have been added after a certain date.	date-time
added_end	Optional	Only return reservations that have been added before a certain date.	date-time
cancelled	Optional	If `true`, only return reservations that have been canceled.	boolean
quote	Optional	If `true`, only return reservations that are quotes.	boolean
tentative	Optional	If `true`, only return reservations that are tentative.	boolean
lynnbrook	Optional	Returns only reservations for specific Lynnbrook properties.	boolean
category_id	Optional	Filters by category ID.	int
category_ids	Optional	Filters by multiple category IDs.	array[int]
merchant_of_record	Optional	Filters by merchant of record.	int
added_by_staff_id	Optional	Filters by the staff member who added the reservation.	int
home_away_sync	Optional	Filters reservations based on HomeAway sync properties.	boolean

Response Definition

Response Item	Description	Data Type
`"reservations"`	A list of reservations matching the query criteria. Each object represents a booking.	array
`"paging"` (if paginated)	Information about the paginated results, including the next page URL and total page count.	object

`"reservations"` Object

Response Item	Description	Data Type
`"id"`	The unique identifier for the reservation.	int
`"unit_id"`	The unique identifier for the unit associated with the reservation.	int
`"reference"`	A reference number for the reservation, provided by the system or external source.	string
`"type"`	The status of the reservation (e.g., `confirmed`, `tentative`).	string
`"management_company_user_id"`	The ID of the property management company handling the reservation.	int
`"details"`	A nested object containing reservation details.	object
`"financials"`	An object containing financial details related to the reservation.	object
`"last_modified"`	The timestamp of the last modification to the reservation.	date-time

`"details"` Object

Response Item	Description	Data Type
`"arrival"`	The scheduled check-in date and time for the reservation.	date-time
`"departure"`	The scheduled check-out date and time for the reservation.	date-time
`"added"`	The date and time when the reservation was created.	date-time
`"cancelled_on"`	The date and time when the reservation was cancelled (If applicable).	date-time
`"scenario"`	Booking scenario code.	int
`"comments"`	A list of comments or notes attached to the reservation.	array
`"guests"`	A list of guests included in the reservation.	array
`"number_of_adults"`	The total number of adult guests in the reservation.	int
`"number_of_children"`	The total number of children in the reservation.	int
`"category"`	The category of the reservation (e.g., TOR for Tour Operator).	string
`"category_id"`	The unique identifier for the reservation category.	int
`"category_description"`	A description of the reservation category.	string
`"secure_details"`	Contains property access details.	object
`"early_check_in"`	Whether the guest is scheduled for early check-in.	boolean
`"late_check_out"`	Whether the guest is scheduled for late check-out.	boolean
`"owner_reservation"`	Whether the reservation is for an owner stay.	boolean

`"comments"` Object

Response Item	Description	Data Type
`"text"`	The text of the comment.	string
`"type"`	The category of the comment (e.g., `general`).	string

`"guests"` Object

Response Item	Description	Data Type
`"id"`	The unique identifier for the guest.	int
`"type"`	The role of the guest in the reservation (e.g., `lead_guest`).	string
`"first_name"`	The first name of the guest.	string
`"last_name"`	The last name of the guest.	string
`"phone_numbers"`	A list of phone numbers associated with the guest.	array[string]
`"email_addresses"`	A list of email addresses associated with the guest.	array[string]
`"customer_address"`	The guest’s address details.	object

`"customer_address"` Object

Response Item	Description	Data Type
`"address_line_1"`	The primary street address of the guest.	string
`"address_line_2"`	Additional address details, if applicable.	string
`"city"`	The city of the guest’s residence.	string
`"state_province"`	The state or province of the guest’s residence.	string
`"country"`	The country of the guest’s residence.	string
`"postal_code"`	The postal or ZIP code of the guest’s residence.	string

`"secure_details"` Object

Response Item	Description	Data Type
`"lock_box_code"`	The lock box code for accessing the property (if applicable).	string
`"gate_code"`	The gate code for accessing the property (if applicable).	string
`"alarm_code"`	The alarm code for the property's security system (if applicable).	string
`"wifi_ssid"`	The Wi-Fi SSID for accessing the property's internet (if applicable).	string
`"wifi_password"`	The Wi-Fi password for accessing the property's internet (if applicable).	string
`"lobby_code"`	The lobby access code for the property (if applicable).	string
`"fitness_room_code"`	The access code for the fitness room (if applicable).	string
`"pool_access_code"`	The access code for the pool area (if applicable).	string
`"beach_access_code"`	The access code for the beach area (if applicable).	string

`"financials"` Object


`"currency"`	The currency in which the reservation is charged (e.g., USD).	string
`"merchant_of_record"`	The entity responsible for processing the payment.	string
`"merchant_of_record_user"`	The user ID of the merchant processing the payment.	int
`"charges"`	An array containing different charges related to the reservation.	array
`"payments"`	A list of payments recorded for the reservation.	array
`"payment_schedule"`	A list of scheduled payments for the reservation.	array
`"total_paid"`	The total amount paid by the guest.	long
`"total_value"`	The total cost of the reservation.	long

`"charges"` Object

Response Item	Description	Data Type
`"item"`	The name of the charge item	string
`"code"`	The code associated with the charge item	string
`"applies_to_id"`	The identifier specifying the charge item it applies to	string
`"quantity"`	The quantity of the charge item	int
`"type"`	The type of the charge item which can be "RENTAL" for rental rate, "CLEAN_FEE" for cleaning fee, "TAX_ONE" for tax one, "TAX_TWO" for tax two, or "EXTRA" for additional fees	string
`"value"`	The amount of the charge item	long

`"payments"` Object

Response Item	Description	Data Type
`"id"`	The unique identifier for the payment	int
`"amount"`	The amount of the payment	long
`"date"`	The date and time when the payment was made	date-time
`"status"`	A description or additional information about the payment	string

`"payment_schedule"` Object

Response Item	Description	Data Type
`"value"`	The amount that is due for the reservation	long
`"value_due"`	The remaining balance due for the payment.	long
`"payment_type"`	The type of payment (e.g., `down_payment`).	string
`"payment_status"`	The status of the payment (e.g., `scheduled`).	string
`"due_date"`	The scheduled due date of the payment.	date-time

`"paging"` Object (If Paginated)

Response Item	Description	Data Type
`"page"`	Current page number.	int
`"page_size"`	Number of records per page.	int
`"next_page_url"`	URL for the next page of results.	string
`"total_page_count"`	Total number of pages in the result set.	int

Sample Request

Example 1: Retrieve Reservations by Date Added

curl --location 'https://api.ciiruspartners.com/v2024.07.31/reservations?page=1&page_size=25&no_total=true&added_start=2025-01-01&added_end=2025-03-05'
--header 'Authorization: Basic {APIUsername:APIPassword}'

Example 2: Retrieve Reservations by Arrival Date

curl --location 'https://api.ciiruspartners.com/v2024.07.31/reservations?arrival_start=2025-03-03&arrival_end=2026-03-30&page=1&page_size=3000&no_total=true'
--header 'Authorization: Basic {APIUsername:APIPassword}'

Sample Response

       {
            "id": 41645050,
            "unit_id": 349691,
            "reference": "",
            "type": "confirmed",
            "management_company_user_id": 51391,
            "details": {
                "arrival": "2025-04-14T16:00:00",
                "departure": "2025-04-17T10:00:00",
                "added": "2025-03-04T07:55:27.69",
                "scenario": 0,
                "comments": [
                    {
                        "text": "",
                        "type": "general"
                    }
                ],
                "guests": [
                    {
                        "id": 7813492,
                        "type": "lead_guest",
                        "first_name": "Test",
                        "last_name": "Guest",
                        "phone_numbers": [
                            ""
                        ],
                        "email_addresses": [
                            "[email protected], [email protected]"
                        ],
                        "customer_address": {
                            "address_line_1": "800 Celebrations Avenue",
                            "address_line_2": "Suite 205",
                            "city": "celebrations",
                            "state_province": "FL",
                            "country": "US",
                            "postal_code": "34747"
                        }
                    }
                ],
                "number_of_adults": 0,
                "number_of_children": 0,
                "category": "PMC",
                "category_id": 14,
                "category_description": "PMC Reservation",
                "secure_details": {
                    "lock_box_code": "",
                    "gate_code": "0606",
                    "alarm_code": "0505",
                    "wifi_ssid": "454547ffgg",
                    "wifi_password": "0808",
                    "lobby_code": "",
                    "fitness_room_code": "",
                    "pool_access_code": "",
                    "beach_access_code": ""
                },
                "early_check_in": false,
                "late_check_out": false,
                "owner_reservation": false
            },
            "financials": {
                "currency": "USD",
                "merchant_of_record": "management_company",
                "merchant_of_record_user": 0,
                "charges": [
                    {
                        "item": "Rental Rate",
                        "code": "Rent",
                        "applies_to_id": "Rent",
                        "quantity": 1,
                        "type": "rental",
                        "value": 415000000000
                    },
                    {
                        "item": "Rental Rate Tax 1",
                        "code": "Rent",
                        "applies_to_id": "Rent",
                        "quantity": 1,
                        "type": "tax_one",
                        "value": 41500000000
                    },
                    {
                        "item": "Booking Fee",
                        "code": "BookingFee",
                        "applies_to_id": "Booking-Fee",
                        "quantity": 1,
                        "type": "booking_fee",
                        "value": 126000000000
                    },
                    {
                        "item": "Booking Fee Tax 1",
                        "code": "BookingFee",
                        "applies_to_id": "Booking-Fee",
                        "quantity": 1,
                        "type": "tax_one",
                        "value": 12600000000
                    },
                    {
                        "id": 28574,
                        "item": "New",
                        "code": "New",
                        "applies_to_id": "28574",
                        "quantity": 1,
                        "type": "extra",
                        "value": 5000000000
                    }
                ],
                "payments": [],
                "payment_schedule": [
                    {
                        "value": 456500000000,
                        "value_due": 456500000000,
                        "payment_type": "down_payment",
                        "payment_status": "scheduled",
                        "due_date": "2025-03-04T07:55:27.69"
                    },
                    {
                        "value": 143600000000,
                        "value_due": 143600000000,
                        "payment_type": "scheduled_payment",
                        "payment_status": "due",
                        "due_date": "2025-03-17T00:00:00"
                    }
                ],
                "total_paid": 0,
                "total_value": 600100000000
            },
            "last_modified": "2025-03-04T07:55:27.73"
        },
      ...
        "paging": {
        "page": 1,
        "page_size": 25
    }
}

If Using Pagination

{
    "reservations": [...],
    "paging": {
        "next_page_url": "https://api.ciiruspartners.com/v2024.07.31/reservations?page=2&page_size=25&added_end=2025-03-05&added_start=2025-01-01",
        "total_page_count": 11,
        "page": 1,
        "page_size": 25
    }
}

Overview

Endpoints Available

Path Parameters

Query String Parameters

Response Definition

"reservations" Object

"details" Object

"comments" Object

"guests" Object

"customer_address" Object

"secure_details" Object

"financials" Object

"charges" Object

"payments" Object

"payment_schedule" Object

"paging" Object (If Paginated)