Overview

This page provides technical guidance to partners who are migrating from the legacy Booking Partner API (SOAP/XML) to the CiiRUS-API (REST/JSON). While other documents explain what has changed and how to plan your migration, this guide focuses on practical implementation patterns and development best practices.

Authentication

The legacy API passed credentials in the XML body:

<APIUserName>your-username</APIUserName>
<APIPassword>your-password</APIPassword>

The Partner-API uses HTTP Basic Authentication instead. Pass the APIUsername:APIPassword as a Base64-encoded value in the Authorization header:

--header 'Authorization: Basic {APIUsername:APIPassword}'

Example:

curl --location 'https://api.ciiruspartners.com/v2024.07.31/units?management_company_user_id=42330' \
--header 'Authorization: Basic {APIUsername:APIPassword}'

HTTP Verbs and REST Conventions

The RESTful design of the CiiRUS-API uses standard HTTP verbs:

📘

Ensure your HTTP client or SDK supports these operations, including setting appropriate headers like Content-Type: application/json.

JSON Payloads

Unlike SOAP, REST uses JSON for both requests and responses. This offers simpler parsing and improved performance. Here's an example of a basic reservation request:

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"
            }
        ]
    }

}'

📘

Use a JSON schema validator or linter during development to ensure well-formed requests.

Error Handling

The CiiRUS-API uses standard HTTP status codes:

Error responses typically include helpful messages:

{
    "message": "Forbidden"
}

{
    "message": "This unit does not exist or you do not have access to it."
}

📘

Always log the full response body for debugging.

Pagination

For endpoints that return lists (e.g., GET /reservations, GET /units), results may be paginated. Use page and page_size parameters to retrieve additional records:

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

📘

Monitor your integration to ensure you’re handling pagination correctly and not missing data.

Versioning

The CiiRUS-API uses date-based versioning:

'https://api.ciiruspartners.com/v2024.07.31/...

📘

When migrating, always target the latest stable version unless instructed otherwise. Monitor for deprecation notices in the API changelog.

Tools for Development

• Postman: Easily test endpoints and inspect JSON structures.
• Insomnia: Great for REST API workflows.
• curl: Ideal for scripting and quick tests.

Tips for Migrating Legacy Integrations

• Avoid 1:1 rewrites. Rethink how your system can be simplified with REST’s flexibility.
• Refactor verbose logic used for XML encoding/decoding.
• Cache static data (unit details, amenities) where possible to reduce load.
• Use logging and request tracing during development to catch unexpected values or edge cases.

Additional Support

If you encounter issues or need development assistance:

📧 [email protected]

🧑‍💻 Interactive API Explorer: docs.ciiruspartners.com

📄 Code Samples: See "Developer Resources" in the Migration Guide