Guides

CiiRUS-API QuickStart Guide

Start-to-Finish Integration in 6 Core Steps

Suggest Edits

Overview

This guide shows you how to go from zero to successfully creating a reservation with the CiiRUS-API. It follows the recommended integration flow and assumes you’ve received your API Username and API Password via your onboarding email.

🧾 Step 0: Authenticate Every Request

All requests must include Basic Authorization header.

Example:

If your credentials are:

PartnerDemo:Secret123

Your base64 encoded string would be:

UGFydG5lckRlbW86U2VjcmV0MTIz

Then you would include this in your headers:

Authorization: Basic UGFydG5lckRlbW86U2VjcmV0MTIz

🔌 Step 1: Get Your Suppliers

Each partner may be connected to one or more Suppliers—CiiRUS clients who provide inventory.

Endpoint:

GET /v2024.07.31/suppliers

Use Case:

  • Retrieve suppliers and Property Manager specific details.
  • Store management_company_user_id for mapping.
  • Verify active suppliers using the active=true query parameter.
  • Filter inventory or reservations by supplier in later requests.

🏘️ Step 2: Get and Map Units

Once you know which suppliers you're connected to, the next step is to fetch their units.

Endpoint:

GET /v2024.07.31/units?management_company_user_id=42330

Use Case:

  • Retrieve units and basic unit details.
  • Map CiiRUS units to your local property data structure.
  • Filter or ignore inactive units ("supplier_enabled": false).

The units returned here which are "supplier_enabled": true but "agent_enabled": false have been enabled by the supplier but still require activation on your end to unlock full API access.

✅ Step 3: Enable Units from Your Side

Even though suppliers have enabled the units, your API connection must also explicitly enable them as well.

Endpoint:

PUT /v2024.07.31/units

Sample Request Body:

[
  {
    "enabled": true,
    "unit_id": 219264
  },
  {
    "enabled": true,
    "unit_id": 219266
  },
  {
    "enabled": true,
    "unit_id": 222033
  }
]

🚧

Skipping this step will result in restricted API behavior for those units.

🔍 Step 4: Retrieve Unit Content (Optional but Recommended)

After enabling, you may want to retrieve supplemental details like:

  • Unit Details: /v2024.07.31/unit_details?management_company_user_id=42330
  • Unit Images: /v2024.07.31/unit_images?management_company_user_id=42330
  • Unit Amenities: /v2024.07.31/unit_amenities?management_company_user_id=42330

These endpoints will help populate your UI or listings.

💵 Step 5: Get Real-Time Pricing & Availability

Now that units are fully enabled, use the /unit_quotes endpoint to validate availability and calculate pricing.

Endpoint:

POST /v2024.07.31/unit_quotes

Sample Request:

POST /v2024.07.31/unit_quotes?management_company_user_id=42330 HTTP/1.1
Host: api.ciiruspartners.com
Content-Type: application/json
Authorization: Basic UGFydG5lckRlbW86U2VjcmV0MTIz

{
  "details": {
    "arrival": "2025-06-15",
    "departure": "2025-06-20" 
  }

}

Sample Response:

{
    "unit_quotes": [
        {
            "management_company_user_id": 0,
            "error": {
                "message": "{\"message\":\"Unit is not available for 5 nights. Valid stays: 0\"}"
            }
        },
        {
            "unit_id": 219265,
            "type": "quote",
            "management_company_user_id": 42330,
            "details": {
                "arrival": "2025-06-15T16:00:00",
                "departure": "2025-06-20T10:00:00",
                "added": "2025-06-02T21:19:37.6990038Z",
                "expiration": "2025-06-02T00:00:00+00:00",
                "guests": [
                    {
                        "type": "lead_guest",
                        "first_name": "Adult 1"
                    }
                ],
                "number_of_adults": 1,
                "number_of_children": 0,
                "number_of_pets": 0,
                "category_id": 16,
                "early_check_in": false,
                "late_check_out": false,
                "owner_reservation": false
            },
            "financials": {
                "rate_set_id": 75114,
                "length_of_stay": false,
                "pool_heat": false,
                "currency": "USD",
                "charges": [
                    {
                        "item": "Rental Rate",
                        "quantity": 1,
                        "type": "rental",
                        "value": 27500000000
                    },
                    {
                        "item": "Rental Rate Tax 1",
                        "applies_to_item": "Rental Rate",
                        "quantity": 1,
                        "type": "tax_one",
                        "value": 1925000000
                    },
                    {
                        "item": "Rental Rate Tax 2",
                        "applies_to_item": "Rental Rate",
                        "quantity": 1,
                        "type": "tax_two",
                        "value": 1375000000
                    },
                    {
                        "item": "Example Fee 1",
                        "code": "Fee1",
                        "applies_to_id": "7417",
                        "quantity": 1,
                        "type": "extra",
                        "value": 825000000
                    },
                    {
                        "item": "Example Fee 1 Tax 1",
                        "applies_to_item": "Example Fee 1",
                        "quantity": 1,
                        "type": "tax_one",
                        "value": 58000000
                    },
                    {
                        "item": "Example Fee 1 Tax 2",
                        "applies_to_item": "Example Fee 1",
                        "quantity": 1,
                        "type": "tax_two",
                        "value": 41000000
                    },
                    {
                        "item": "Example Fee 2",
                        "code": "Fee2",
                        "applies_to_id": "7418",
                        "quantity": 1,
                        "type": "extra",
                        "value": 1000000000
                    },
                    {
                        "item": "Example Fee 2 Tax 1",
                        "applies_to_item": "Example Fee 2",
                        "quantity": 1,
                        "type": "tax_one",
                        "value": 70000000
                    },
                    {
                        "item": "Example Fee 2 Tax 2",
                        "applies_to_item": "Example Fee 2",
                        "quantity": 1,
                        "type": "tax_two",
                        "value": 50000000
                    },
                    {
                        "item": "Example Fee 3",
                        "code": "Fee3",
                        "applies_to_id": "7419",
                        "quantity": 1,
                        "type": "extra",
                        "value": 1000000000
                    },
                    {
                        "item": "Example Fee 3 Tax 1",
                        "applies_to_item": "Example Fee 3",
                        "quantity": 1,
                        "type": "tax_one",
                        "value": 70000000
                    },
                    {
                        "item": "Example Fee 3 Tax 2",
                        "applies_to_item": "Example Fee 3",
                        "quantity": 1,
                        "type": "tax_two",
                        "value": 50000000
                    },
                    {
                        "item": "Fee Example 6",
                        "code": "Fee6",
                        "applies_to_id": "7422",
                        "quantity": 1,
                        "type": "extra",
                        "value": 500000000
                    },
                    {
                        "item": "Fee Example 6 Tax 1",
                        "applies_to_item": "Fee Example 6",
                        "quantity": 1,
                        "type": "tax_one",
                        "value": 35000000
                    },
                    {
                        "item": "Fee Example 6 Tax 2",
                        "applies_to_item": "Fee Example 6",
                        "quantity": 1,
                        "type": "tax_two",
                        "value": 25000000
                    },
                    {
                        "item": "Accidental Damage Insurance",
                        "code": "ADI",
                        "applies_to_id": "21728",
                        "quantity": 1,
                        "type": "extra",
                        "value": 7500000000
                    },
                    {
                        "item": "Daily Amount Fee Example",
                        "code": "DAY",
                        "applies_to_id": "24651",
                        "quantity": 1,
                        "type": "extra",
                        "value": 1750000000
                    },
                    {
                        "item": "Property Protection Fee",
                        "code": "CP-STD",
                        "applies_to_id": "25011",
                        "quantity": 1,
                        "type": "extra",
                        "value": 6500000000
                    }
                ],
                "payment_schedule": [
                    {
                        "value": 50274000000,
                        "value_due": 50274000000,
                        "payment_type": "down_payment",
                        "payment_status": "due",
                        "due_date": "2025-06-02T00:00:00Z"
                    }
                ],
                "total_value": 50274000000,
                "payment_taken_by": 1
            }
        },
      ],
    "paging": {
        "next_page_url": "https://api.ciiruspartners.com/v2024.07.31/unit_quotes?page=2&page_size=25&management_company_user_id=42330",
        "total_page_count": 3,
        "page": 1,
        "page_size": 25
    }
}

🧾 Step 6: Create a Reservation

Once you have a valid quote and confirmed availability, you're ready to create a reservation.

Endpoint:

POST /v2024.07.31/reservations

Sample Request:

{
    "unit_id": 219265,
    "management_company_user_id": 42330,
    "reference": "YourAppsResID",
    "details": {
        "arrival": "2026-07-07T16:00:00",
        "departure": "2026-07-10T10:00:00",        
        "guests": [
            {
                "type": "lead_guest",
                "first_name": "Test",
                "last_name": "Guest"
            }
        ],
        "number_of_adults": 1
    }

}

🚧

Currency Format Notice

All currency values in the API are returned in fixed-point format using a scale of 10⁸. For example, a value of 100000000 represents 1.00. This ensures precision in financial calculations. Be sure to adjust your implementation accordingly when parsing or displaying amounts.

✅ You're Live!

With these steps, you've completed the core flow:

  1. Identify connected suppliers
  2. Map and enable units
  3. Retrieve unit metadata
  4. Retrieve pricing and availability
  5. Create reservations with ease

💡 Tips

  • Run GET /v2024.07.31/suppliers and GET /v2024.07.31/units regularly to check for new or deactivated suppliers or inventory.
  • Log quote/reservation failures, including the x-amz-meta-guid from the Response header, and reach out for guidance if needed.
  • Don't forget to test your integration against edge cases like same-day arrivals or far-future bookings.

Updated about 20 hours ago