Data Format Standards

This page documents the standard formats and structures used across all CASY API responses.

Response Format

All successful responses follow a consistent JSON structure with sensitive fields automatically removed:

{
  "ok": true,
  "requested_hotel": "9994",
  "target_db": "awscasyfront_demo_BK",
  "filters": { ... },
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3
  },
  "sort": {
    "by": "Arrival",
    "order": "desc"
  },
  "meta": {
    "query_time_ms": 123.45
  },
  "reservations": [ ... ]
}

Note: The list key varies by endpoint (e.g., reservations, addresses, settings).

Date & Time Formats

Data Type	Format	Example	Notes
Date Only	`YYYY-MM-DD`	2026-05-21	Used for birthdays, arrival, departure dates
DateTime	`YYYY-MM-DD HH:MM:SS`	2026-05-21 14:30:00	Server timestamps in UTC
Date Range Parameters	`arrival_from=YYYY-MM-DD&arrival_to=YYYY-MM-DD`	arrival_from=2026-05-01&arrival_to=2026-05-31	Inclusive date ranges

Currency & Numeric Formats

Data Type	Format	Example	Notes
Price/Amount	Decimal (2 places)	123.45	Always includes decimal point; 0.00 for zero
Integer IDs	Numeric, no decimals	9994	CASY ID, hotel ID, reservation ID, etc.
Percentage	0-100 (decimal)	75.5	Occupancy rates, discount percentages
Boolean	0 or 1 (integer)	1 = true, 0 = false	In some endpoints, may also be true/false

Location & Language Data

Data Type	Format	Example	Notes
Country Code	ISO 3166-1 alpha-2	CH, DE, IT, FR	2-letter uppercase country codes
Country (Full)	ISO 3166-1 alpha-3	CHE, DEU, ITA, FRA	3-letter uppercase country codes (when extended)
Language ID	Integer	1 = German, 2 = French, 3 = Italian, 4 = English	System-specific language identifiers
Email	RFC 5322 format	guest@example.com	Lowercase preferred; validated on input
Phone	International format (recommended)	+41 44 123 4567	Spaces optional; stored as provided

Reservation Object Structure

{
  "ReservationId": 12345,
  "ReservationStatus": 1,
  "ReservationType": 2,
  "Arrival": "2026-05-21",
  "Departure": "2026-05-25",
  "GuestFirstName": "John",
  "GuestLastName": "Doe",
  "GuestEmail": "john@example.com",
  "NumberOfPersons": 2,
  "NumberOfRooms": 1,
  "TotalPrice": 450.00,
  "PaidAmount": 450.00,
  "ChannelId": 1,
  "CreateDate": "2026-05-20 10:30:00",
  "LastUpdateDate": "2026-05-20 14:15:00"
}

Room Object Structure

{
  "RoomId": 501,
  "RoomNumber": "301",
  "RoomType": "Deluxe Double",
  "FloorId": 3,
  "Beds": 1,
  "MaxCapacity": 2
}

Address Object Structure

{
  "AddressId": 54321,
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "john@example.com",
  "Street": "Main Street 123",
  "Street2": "Apt 4B",
  "PostalCode": "8000",
  "City": "Zurich",
  "Country": "CH",
  "Phone": "+41 44 123 4567",
  "Mobile": "+41 79 123 4567",
  "BirthDate": "1985-03-15",
  "Nationality": "CHE"
}

Account/Billing Object Structure

{
  "AccountId": 98765,
  "ReservationId": 12345,
  "AccountName": "Room Charge",
  "Description": "2 nights, 1 room",
  "Amount": 450.00,
  "Currency": "CHF",
  "Meals": 1,
  "Status": 0,
  "Active": 1,
  "BalanceType": 1,
  "Quantity": 2
}

Settings & Reference Data

Reference data objects use consistent naming conventions:

// Reservation Statuses
{
  "ReservationStatusId": 1,
  "ReservationStatus": "Confirmed",
  "ReservationStatusOrder": 1,
  "ReservationColor": "#00AA00",
  "translations": [
    { "LanguageId": 1, "ReservationStatusName": "Bestätigt" },
    { "LanguageId": 2, "ReservationStatusName": "Confirmé" }
  ]
}

// Channels
{
  "ChannelId": 1,
  "Name": "Direct",
  "ChannelOrder": 1,
  "ChannelColor": "#0066CC"
}

// Meals
{
  "MealId": 4,
  "Abbreviation": "ZF",
  "MealOrder": 1,
  "Breakfast": 1,
  "Lunch": 0,
  "Dinner": 0,
  "Night": 1
}

Authentication & Pagination

Authorization Header

Authorization: Bearer your-token-value-here

Token values are 32+ character alphanumeric strings, case-sensitive.

Pagination Parameters

Parameter	Type	Default	Description
`page`	integer	1	Current page number (1-indexed)
`limit` / `per_page`	integer	50 (or 100)	Results per page (max: 1000)
`sort_by`	string	Arrival	Field to sort by
`sort_order`	string	desc	Sort direction: asc or desc

Response Pagination Structure

{
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 250,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  },
  "sort": {
    "by": "Arrival",
    "order": "desc"
  }
}

Field Selection (Where Supported)

Some endpoints support selective field retrieval:

GET /v1/reservations/9994?fields=ReservationId,GuestFirstName,Arrival,TotalPrice

This optimizes bandwidth by returning only needed fields. Only "safe" fields are allowed; sensitive data is filtered automatically.