CASY API

Hotel Reservation & Management API

Overview Endpoints Data Format Error Codes Changelog
Notice: This API is for authorized users only. All usage is monitored and logged. Unauthorized access attempts will be investigated.

Your Credentials

Saved locally in your browser for endpoint testing.

API Endpoints

All API endpoints require authentication via bearer token unless otherwise noted.

Use the Test This Endpoint button in each endpoint card.

Health & Status

GET /health/hotels/{casyId} Auth
Hotel-specific health check (includes tenant DB status)

Token Introspection

GET /introspect Auth
View your token permissions, allowed hotels, and available endpoints
Response Includes
token - Token metadata (ID, expiration, days remaining)
allowed_hotels - List of hotel/CASY IDs you can access
rate_limit - Your rate limiting configuration (requests per window)
actions - All actions/permissions granted to this token with descriptions
available_endpoints - Complete list of endpoints you can call with this token

Reservations

GET /reservations/{casyId} Auth
Get reservations with comprehensive filtering, pagination, and optional nested data
Query Parameters
Arrival Date Filters
arrival_from (string) - Arrival date start (YYYY-MM-DD)
arrival_to (string) - Arrival date end (YYYY-MM-DD)
start_date (string) - Alias for arrival_from (backward compatible)
end_date (string) - Alias for arrival_to (backward compatible)
Other Date Filters
departure_from (string) - Departure date start (YYYY-MM-DD)
departure_to (string) - Departure date end (YYYY-MM-DD)
created_from (string) - Creation date start (YYYY-MM-DD)
created_to (string) - Creation date end (YYYY-MM-DD)
updated_from (string) - Last updated date start (YYYY-MM-DD)
start_in_house_date (string) - In-house period start — returns reservations overlapping this date range (YYYY-MM-DD)
end_in_house_date (string) - In-house period end (YYYY-MM-DD)
Status & Booking Filters
status (integer) - Reservation status code (CSV supported, e.g. 1,2,3)
notify_only (boolean) - Only notification/inquiry reservations (0 requires reservations.view_non_notifiable permission)
payed (boolean) - Payment status (0 or 1)
final_reservation (integer) - Filter by reservation type ID (CSV supported)
channel_id (integer) - Filter by booking channel ID (CSV supported)
storno_only (boolean) - Only cancelled reservations (cannot combine with exclude_storno)
exclude_storno (boolean) - Exclude cancelled reservations (cannot combine with storno_only)
Range Filters
min_persons (integer) - Minimum number of persons
max_persons (integer) - Maximum number of persons
min_rooms (integer) - Minimum number of rooms
max_rooms (integer) - Maximum number of rooms
min_nights (integer) - Minimum number of nights
max_nights (integer) - Maximum number of nights
min_price (number) - Minimum total price
max_price (number) - Maximum total price
Guest Filters
person (string) - Search by guest name (partial match)
first_name (string) - Filter by guest first name (partial match on linked address)
last_name (string) - Filter by guest last name (partial match on linked address)
email (string) - Filter by guest email (partial match on linked address)
country (string) - Filter by guest country ID or ISO code (e.g. CH)
address_id (integer) - Filter by exact address ID
remarks (string) - Search reservations having matching text in Remarks.Remarks
Room & Hotel Filters
hotel_ids (string) - Filter by specific hotel IDs (comma-separated; pass 0 to include all hotels in CASY)
room_id (integer) - Filter by room ID (CSV supported)
room_number (string) - Filter by room number
Data Inclusion
include_rooms (boolean) - Include room data for each reservation
include_accounts (boolean) - Include account rows for each reservation (requires accounts permission). Each account row includes a translations array when multilingual labels exist, and the response also includes top-level settings.meals and settings.accounts_multilanguage lookup tables.
include_legal_accounts (boolean) - Include per-reservation legal revenue allocation, gross-inclusive VAT amounts, VAT summary, and grand total. account_allocations maps every source AccountId to its legal rows; aggregate legal rows include source_account_ids. Legal rows include all available translations. Requires include_accounts=1 and the same account permission. The alias include_legals_accounts is also accepted.
include_address (boolean) - Include guest address (Reservations.AddressId); also sets the backward-compat address key
include_guest_address (boolean) - Include guest address as guest_address key (Reservations.AddressId — who is staying)
include_billing_address (boolean) - Include billing address as billing_address key (Reservations.InvoiceAddressId — who pays)
include_language (boolean) - Enrich each included address with title-linked language data (requires at least one address include flag)
include_companions (boolean) - Include companion list per reservation (requires companions permission)
include_hotel (boolean) - Include hotel name and ID resolved from room data
include_persons (boolean) - Include person counts per customer type (adults, children, seniors) from linked account rows
Allowed Settings
notify_only (0|1) - Allowed values are 0 or 1. Use 0 only with admin or reservations.view_non_notifiable permission.
include_* (0|1) - All include flags accept 0/1 (also true/false).
fields (string) - Optional comma-separated reservation columns. Allowed values: ReservationId, TitleId, ViewAddressId, AddressId, InvoiceAddressId, Arrival, Departure, NumberDays, NumberPersons, NumberRooms, SubRoomsCount, Observations, Remarks, Payed, Notify, Person, UpdateDate, CreationDate, ChannelId, ReservationStatus, Price.
notify output - To expose the reservation notify flag in response rows, add Notify to fields (example: fields=ReservationId,Arrival,Departure,Person,Notify).
Pagination & Sorting
limit (integer) - Results per page (default: 50, max: 200)
page (integer) - Page number (default: 1)
sort_by (string) - Sort field: ReservationId, Arrival, Departure, CreationDate, UpdateDate, Price, NumberPersons, NumberRooms, Person (default: Arrival)
sort_order (string) - Sort direction: asc or desc (default: desc)
GET /reservations/{casyId}/all Auth
Alias for /reservations/{casyId} — kept for backward compatibility, accepts identical parameters
GET /reservations/{casyId}/{reservationId} Auth
Get single reservation with optional nested data
Query Parameters
Field Selection
fields (string) - Comma-separated list of allowed reservation columns. Allowed values: ReservationId, TitleId, ViewAddressId, AddressId, InvoiceAddressId, Arrival, Departure, NumberDays, NumberPersons, NumberRooms, SubRoomsCount, Observations, Remarks, Payed, Notify, Person, UpdateDate, CreationDate, ChannelId, ReservationStatus, Price (e.g. ReservationId,Arrival,Person,Notify)
Data Inclusion
include_accounts (boolean) - Include account rows (requires accounts permission)
include_legal_accounts (boolean) - Include legal revenue accounts, source AccountId mappings, translations, and VAT allocation for this reservation. Requires include_accounts=1; include_legals_accounts is accepted as an alias.
include_companions (boolean) - Include companion list (requires companions permission)
include_rooms (boolean) - Include room data (RoomId, RoomNumber, RoomType)
include_address (boolean) - Include guest address (Reservations.AddressId); sets the address key
include_guest_address (boolean) - Include guest address as guest_address key (Reservations.AddressId — who is staying)
include_billing_address (boolean) - Include billing address as billing_address key (Reservations.InvoiceAddressId — who pays)
include_language (boolean) - Enrich included address(es) with title-linked language data (requires at least one address include flag)
include_persons (boolean) - Include person counts per customer type (adults, children, seniors) from linked account rows

Booking Changes

GET /booking-changes/{casyId} Auth
Download immutable booking changes detected by the booking scanner using cursor-based pagination
Required Permission
reservations:read - The token must be allowed to read reservations for the requested CASY ID.
Query Parameters
after (integer) - Return changes after this cursor (default: 0).
until (integer) - Freeze pagination at this watermark. Use the first response's until value for subsequent pages.
limit (integer) - Maximum changes per response (default: 1000, max: 1000).
Response Includes
changes - Ordered upsert or delete events with immutable booking payloads and hashes.
next_cursor - Pass this value as after when requesting the next page.
until - Stable upper boundary for the current download cycle.
high_watermark - Most recent available change ID at request time.
has_more - Whether another page exists before the until watermark.

Addresses

GET /addresses/{casyId} Auth
Get addresses with filtering and pagination (sensitive fields automatically removed)
Query Parameters
first_name (string) - Filter by first name
last_name (string) - Filter by last name
email (string) - Filter by email address
address (string) - Filter by address text (partial match on Street1 or Street2, e.g. "Seven Town House")
remarks (string) - Filter addresses that have matching text in Remarks.Remarks (example: test)
city (string) - Filter by city name or numeric city ID
country (string) - Filter by country ID or ISO code
include_remarks (boolean) - Include remarks linked by Remarks.id_Address (use 1/true)
include_language (boolean) - Include nested language object resolved from title mapping (use 1/true)
limit (integer) - Results per page (default: 50)
page (integer) - Page number (default: 1)
sort_by (string) - Sort field such as FirstName, LastName, Email, City, Country, PostalCode, or AddressId
sort_order (string) - Sort direction: asc or desc (default: asc)
example (request) - /v1/addresses/{casyId}?remarks=test&include_remarks=1&include_language=1&sort_by=AddressId&sort_order=asc
GET /addresses/{casyId}/{addressId} Auth
Get single address details (sensitive fields automatically removed)

Settings & Reference Data

GET /settings/hotels/{casyId}/reservation-statuses Auth
Get all reservation statuses with multilanguage translations
GET /settings/hotels/{casyId}/reservation-types Auth
Get all reservation types with multilanguage translations
GET /settings/hotels/{casyId}/meals Auth
Get meal reference data with multilingual labels
GET /settings/hotels/{casyId}/channels Auth
Get channel reference data ordered by ChannelOrder
GET /settings/hotels/{casyId}/countries Auth
Get countries reference data
GET /settings/hotels/{casyId}/languages Auth
Get available languages (LanguageId, Abreviation, Language, Default, isInternal)
GET /settings/hotels/{casyId}/titles Auth
Get titles; optionally include linked language object
Query Parameters
include_language (boolean) - Include linked language details for each title (default: true)
POST /settings/hotels/{casyId}/titles/resolve Auth
Resolve a recommended TitleId using local Ollama classification with fallback rules. For tester usage on this page, pass parameters as query values.
Required Permission
casy_basic:title_resolve - Dedicated CASY basic action for this endpoint (admin action also bypasses)
Query Parameters
address_id (integer) - Address ID to classify (optional if first_name + last_name are provided)
first_name (string) - First name lookup key (required with last_name when address_id is not provided)
last_name (string) - Last name lookup key (required with first_name when address_id is not provided)
city (string) - Optional city hint for lookup and LLM context
country (string) - Optional country hint (CountryId or ISO code like CH) for lookup and LLM context
GET /settings/hotels/{casyId}/room-types Auth
Get room types reference data
GET /settings/hotels/{casyId}/customer-types Auth
Get customer/person types (adults, children, seniors, etc.) with multilanguage translations. The tourism_free flag indicates whether the type is exempt from the tourism tax.
Query Parameters
language_id (integer) - Filter translations to a single language (optional)

Hotels

GET /hotels Auth
List all accessible hotels
GET /hotels/{casyId} Admin
Get single hotel mapping and database connection info