Overview

The Create Reservation function allows you to create and add new Bookings using the CiiRUS-API. This guide provides instructions on the required parameters and values to successfully generate bookings for available units within your Inventory. With this feature, you can integrate booking functionality into your application.

Partners can choose between two options when creating reservations:

Simplified Method (Recommended)
1. Partners provide the basic reservation information and allow the CiiRUS system to calculate all charges, including taxes. The full financial breakdown is returned in the response.
Custom Financials Method
1. Partners may choose to supply a financials object with specific charges (e.g., rent, extras, etc.). As taxes cannot be controlled via the API when using this method, only include base charges — tax totals will be calculated systematically and returned in the response.

🗨️
For Option 2, we recommend first retrieving a quote using the Quote endpoint. The response provides a full breakdown of the reservation cost, which can then be used to assist with populating the reservation request accurately.

Endpoints Available

Method	Endpoint	Description
POST	v2024.07.31/reservations	Use this endpoint to create a reservation.

Body Parameters

Parameter	Required / Optional	Description	Data Type
`"unit_id"`	Required	Unique Identifier for Unit in Inventory for the reservation.	int
`"reference"`	Optional	Optional external reference number for the reservation.	string
`"type"`	Required	Indicates the type of reservation, such as "confirmed".	string
`"details"`	Required	An object containing specific details related to the reservation.	object
`"financials"`	Optional	An object containing financial details related to the booking.	object
`"total_amount"`	Optional	The total amount of the booking, including all charges. Used only if `"financials"` is included.	int

`"details"` Object Body Parameters

Parameter	Required / Optional	Description	Data Type
`"arrival"`	Required	The arrival date for the reservation.	date-time
`"departure"`	Required	The departure date for the reservation.	date-time
`"added"`	Optional	The date-time the reservation is being created.	date-time
`"guests"`	Required	An object containing specific details related to the guest(s) associated with the reservation.	array[objects]
`"number_of_adults"`	Optional	The number of adults included in the booking	int
`"number_of_children"`	Optional	The number of children included in the booking	int
`"number_of_pets"`	Optional	The number of pets included in the booking	int
`"category_id"`	Optional	An array containing details about additional Party Members	int
`"comments"`	Optional	Object holding reservation comments.	array[objects]

`"guests"` Object Body Parameters

Parameter	Required / Optional	Description	Data Type
`"id"`	Optional	CRM ID of the lead guest.	int
`"type"`	Required	The type of guest, "lead_guest".	string
`"title"`	Optional	The title of the lead guest.	string
`"first_name"`	Required	The first name of the lead guest.	string
`"last_name"`	Required	The last name of the lead guest.	string
`"age"`	Optional	The age of the lead guest.	string
`"phone_numbers"`	Optional	The phone number(s) of the lead guest.	array[strings]
`"email_addresses"`	Optional	The email address(es) of the lead guest.	array[strings]
`"address"`	Optional	The mailing address of the lead guest.	array[objects]
`"notes"`	Optional	Additional notes to add against the Lead Guest.	string
`"allow_marketing_emails"`	Optional	Indicates whether the Lead Guest allows marketing emails.	boolean
`"airbnb_guest_id"`	Optional	Unique identifier for an Airbnb guest.	string

`"address"` Object Body Parameters

Parameter	Required / Optional	Description	Data Type
`"address_line_1"`	The first line of the lead guest's mailing address.	string	string
`"address_line_2"`	The second line of the lead guest's mailing address.	string	string
`"city"`	The City of the lead guest's mailing address.	string	string
`"state_province"`	The State or Province of the lead guest's mailing address.	string	string
`"country"`	The Country of the lead guest's mailing address.	string	string
`"postal_code"`	The ZIP or Postal Code of the lead guest's mailing address.	string	string

`"comments"` Object Body Parameters

Parameter	Required / Optional	Description	Data Type
`"text"`	Optional	The text of the comment	string
`"type"`	Optional	The type of comment. See Valid Enumerations for more details.	string

`"financials"` Object Body Parameters

Parameter	Required / Optional	Description	Data Type
`"quote_as_super_site_user_id"`	Optional	Allows quoting as a specific user.	int
`"length_of_stay"`	Optional	Indicates if length-of-stay pricing is used.	boolean
`"pool_heat"`	Optional	Indicates if pool heat is desired/included.	boolean
`"discount_code"`	Optional	Optional Discount Code, provided by the Supplier.	string
`"charges"`	Optional	Individual reservation charges.	array[objects]
`"total_amount"`	Optional	The total value of the reservation.	int
`"payment_schedule"`	Optional	Payment breakdown with due dates.	array[objects]

`"charges"` Object Body Parameters

Parameter	Required / Optional	Description	Data Type
`"item"`	Optional	The name of the charge item.	string
`"id"`	Optional	The unique identifier for the charge item	string
`"code"`	Optional	The code associated with the charge item	string
`"applies_to_id"`	Optional	The identifier specifying the charge item it applies to	string
`"quantity"`	Optional	The quantity of the charge item	int
`"type"`	Optional	The type of the charge item (see Valid Enumerations for more details.)	string

`"payment_schedule"` Object Body Parameters

Parameter	Required / Optional	Description	Data Type
`"amount"`	Optional	Scheduled amount	int
`"due_date"`	Optional	Due date of the payment.	date-time

Response Definition

Response Item	Description	Data Type
`"id"`	Unique identifier for the reservation.	int
`"unit_id"`	Unique identifier for the unit associated with the reservation.	int
`"reference"`	Status of the reservation (e.g., "confirmed").	string
`"type"`	Denotes the source of the booking, like "TestSource".	string
`"management_company_user_id"`	Unique identifier for the Supplier associated with the reservation.	int
`"details"`	An object containing details about the associated reservation.	object
`"financials"`	An object containing financial details related to the reservation.	object
`"last_modified"`	Timestamp of the last modification.	date-time

`"details"` Object

Response Item	Description	Data Type
`"arrival"`	Date and time of the guest's arrival.	date-time
`"departure"`	Date and time of the guest's departure.	date-time
`"added"`	Timestamp when the reservation was added.	date-time
`"scenario"`	Reservation Scenario ID.	int
`"comments"`	An array of comment objects.	array[objects]
`"guests"`	An array containing details about the guests.	array[objects]
`"number_of_adults"`	Number of adults in the reservation.	int
`"number_of_children"`	Number of children in the reservation.	int
`"number_of_pets"`	Number of pets in the reservation.	int
`"category"`	Reservation category code (e.g., "TOR").	string
`"category_id"`	Internal ID for the category.	int
`"category_description"`	Human-readable description of the category.	string
`"secure_details"`	An object containing access codes and secure info.	array[objects]
`"early_check_in"`	Indicates if early check-in has been allowed.	boolean
`"late_check_out"`	Indicates if late check-out has been allowed.	boolean
`"arrival_departure_info"`	Additional arrival/departure instructions	string
`"owner_reservation"`	Indicates whether the booking is an owner reservation or not.	boolean
`"unit_name"`	The supplier configured name of the reserved unit.	string

`"comments"` Array

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

`"guests"` Array

Response Item	Description	Data Type
`"id"`	Unique identifier for the lead guest.	int
`"type"`	Guest type, like "lead_guest".	string
`"first_name"`	The first name of the lead guest.	string
`"last_name"`	The last name of the lead guest.	string
`"phone_numbers"`	The phone number(s) of the lead guest.	array[string]
`"email_addresses"`	The email address(es) of the lead guest.	array[string]
`"customer_address"`	The mailing address of the lead guest.	array[objects]

`"customer_address"` Object

Response Item	Description	Data Type
`"address_line_1"`	The first line of the lead guest's mailing address.	string
`"address_line_2"`	The second line of the lead guest's mailing address.	string
`"city"`	The City of the lead guest's mailing address.	string
`"state_province"`	The State or Province of the lead guest's mailing address.	string
`"country"`	The Country of the lead guest's mailing address.	string
`"postal_code"`	The ZIP or Postal Code of the lead guest's mailing address.	string

`"secure_details"` Object

Response Item	Description	Data Type
`"lock_box_code"`	Lockbox code for unit access, if applicable.	string
`"gate_code"`	Gate access code, if applicable, and configured by the Supplier.	string
`"alarm_code"`	Alarm code for unit access, if applicable, and configured by the Supplier.	string
`"wifi_ssid"`	WiFi network name, if applicable, and configured by the Supplier.	string
`"wifi_password"`	WiFi password, if applicable, and configured by the Supplier.	string
`"lobby_code"`	Lobby access code, if applicable, and configured by the Supplier.	string
`"fitness_room_code"`	Fitness room access code, if applicable, and configured by the Supplier.	string
`"pool_access_code"`	Pool access code, if applicable, and configured by the Supplier.	string
`"beach_access_code"`	Beach access code, if applicable, and configured by the Supplier.	string

`"financials"` Object

Response Item	Description	Data Type
`"currency"`	The currency used for the reservation.	string
`"merchant_of_record"`	Identifies who the merchant of record is.	string
`"merchant_of_record_user"`	The ID of the user who is the merchant of record.	int
`"charges"`	An array of financial charge items.	array[objects]
`"payments"`	An array of payments that were made for the reservation.	array[objects]
`"payment_schedule"`	An array of scheduled payments.	array[objects]
`"total_paid"`	The total amount paid for the reservation to date.	int
`"total_value"`	The total booking value including taxes.	int

`"charges"` Array

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.	string
`"value"`	The amount of the charge item	int

`"payments"` Array

Response Item	Description	Data Type

`"payment_schedule"` Array

Response Item	Description	Data Type
`"value"`	The total payment value.	int
`"value_due"`	The amount still due for payment.	int
`"payment_type"`	The type of payment (e.g., "scheduled_payment")	string
`"payment_status"`	The status of the payment (e.g., "due")	string
`"due_date"`	The due date for the payment.	string

Sample Request (Option 1)

curl --location 'https://api.ciiruspartners.com/v2024.07.31/reservations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {APIUsername:APIPassword}' \
--data '{
    "unit_id": 219264,
    "management_company_user_id": 42330,
    "details": {
        "arrival": "2025-07-07T16:00:00",
        "departure": "2025-07-10T10:00:00",        
        "guests": [
            {
                "type": "lead_guest",
                "first_name": "Test",
                "last_name": "Guest"
            }
        ]
    }

}'

Sample Request (Option 2)

Sample Response

{
    "id": 41853135,
    "unit_id": 219264,
    "reference": "",
    "type": "confirmed",
    "management_company_user_id": 42330,
    "details": {
        "arrival": "2025-07-07T16:00:00",
        "departure": "2025-07-10T10:00:00",
        "added": "2025-04-15T15:12:05.837",
        "scenario": 12,
        "comments": [
            {
                "text": "",
                "type": "general"
            }
        ],
        "guests": [
            {
                "id": 7966921,
                "type": "lead_guest",
                "first_name": "Test",
                "last_name": "Guest",
                "phone_numbers": [
                    ""
                ],
                "email_addresses": [
                    ""
                ],
                "customer_address": {
                    "address_line_1": "",
                    "address_line_2": "",
                    "city": "",
                    "state_province": "",
                    "country": "",
                    "postal_code": ""
                }
            }
        ],
        "number_of_adults": 1,
        "number_of_children": 0,
        "category": "TOR",
        "category_id": 16,
        "category_description": "Tour Operator 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": true,
        "late_check_out": false,
        "arrival_departure_info": "",
        "owner_reservation": false,
        "unit_name": "Test Property 1"
    },
    "financials": {
        "currency": "USD",
        "merchant_of_record": "agent",
        "merchant_of_record_user": 66673,
        "charges": [
            {
                "item": "Rental Rate Tax 1",
                "code": "Rent",
                "applies_to_id": "Rent",
                "quantity": 1,
                "type": "tax_one",
                "value": 3900000000
            },
            {
                "item": "Rental Rate Tax 2",
                "code": "Rent",
                "applies_to_id": "Rent",
                "quantity": 1,
                "type": "tax_two",
                "value": 3600000000
            },
            {
                "item": "Clean Fee",
                "code": "Clean",
                "applies_to_id": "Clean",
                "quantity": 1,
                "type": "clean_fee",
                "value": 28000000000
            },
            {
                "item": "Clean Fee Tax 1",
                "code": "Clean",
                "applies_to_id": "Clean",
                "quantity": 1,
                "type": "tax_one",
                "value": 1820000000
            },
            {
                "item": "Clean Fee Tax 2",
                "code": "Clean",
                "applies_to_id": "Clean",
                "quantity": 1,
                "type": "tax_two",
                "value": 1680000000
            }
        ],
        "payments": [],
        "payment_schedule": [
            {
                "value": 31500000000,
                "value_due": 31500000000,
                "payment_type": "scheduled_payment",
                "payment_status": "due",
                "due_date": "2025-06-09T00:00:00"
            }
        ],
        "total_paid": 0,
        "total_value": 99000000000
    },
    "last_modified": "2025-04-15T19:12:05.143"
}

Overview

🗨️

Endpoints Available

Body Parameters

"details" Object Body Parameters

"guests" Object Body Parameters

"address" Object Body Parameters

"comments" Object Body Parameters

"financials" Object Body Parameters

"charges" Object Body Parameters

"payment_schedule" Object Body Parameters

Response Definition

"details" Object

"comments" Array

"guests" Array

"customer_address" Object

"secure_details" Object

"financials" Object

"charges" Array

"payments" Array

"payment_schedule" Array

Sample Request (Option 1)

Sample Request (Option 2)

Sample Response

`"details"` Object Body Parameters

`"guests"` Object Body Parameters

`"address"` Object Body Parameters

`"comments"` Object Body Parameters

`"financials"` Object Body Parameters

`"charges"` Object Body Parameters

`"payment_schedule"` Object Body Parameters

`"details"` Object

`"comments"` Array

`"guests"` Array

`"customer_address"` Object

`"secure_details"` Object

`"financials"` Object

`"charges"` Array

`"payments"` Array

`"payment_schedule"` Array