Data Model

Canonical field definitions for reservations, guests, stays, and charges.

Overview

Hotelinking normalizes all data from different PMS and CRS systems into a canonical data model. Regardless of what your API returns, data is mapped to these standard fields before delivery to destinations. This ensures consistent data structure across all integrations.

Entity Relationship

Every reservation is the top-level entity, containing one or more guests, zero or more stays (room assignments), and zero or more extras (charges and services).

entity structure

Reservation
├── guests[]    (1 or more)
├── stays[]     (1 or more room assignments)
└── extras[]    (0 or more charges / services)

Reservation Fields

The reservation is the root entity. All fields except those marked as required may be absent depending on the source system.

Field	Type	Required	Description
`reservation_id`	string	Yes	Unique reservation identifier from the PMS
`confirmation_number`	string	No	External confirmation or booking reference
`booking_id`	string	No	Booking engine reference (for CRS integrations)
`hotel_id`	string	No	Property identifier in the source system
`hotel_name`	string	No	Property name
`check_in`	string	Yes	Check-in date (ISO 8601: YYYY-MM-DD)
`check_out`	string	Yes	Check-out date (ISO 8601: YYYY-MM-DD)
`booking_date`	string	No	Date the reservation was created
`status`	string	Yes	Reservation status (see Status Values below)
`channel`	string	No	Booking channel (e.g., "direct", "booking.com")
`source`	string	No	Booking source or origin
`agency`	string	No	Travel agency name
`agency_code`	string	No	Travel agency code
`market_segment`	string	No	Market segment classification
`nights`	number	No	Number of nights (auto-calculated if not provided)
`amount`	number	No	Total reservation amount (gross)
`amount_net`	number	No	Net amount (after commissions)
`currency`	string	No	ISO 4217 currency code (e.g., "EUR", "USD")
`external_created_at`	string	No	Creation timestamp from source (ISO 8601)
`external_updated_at`	string	No	Last update timestamp from source (ISO 8601)
`guests`	Guest[]	Yes	Array of guest records
`stays`	Stay[]	No	Array of stay / room records
`extras`	Extra[]	No	Array of charge / extra records

Status Values

Reservation statuses are normalized from source system codes into these canonical values.

confirmed

Active reservation

checked_in

Guest currently in house

checked_out

Guest has departed

cancelled

Reservation cancelled

no_show

Guest did not arrive

pending

Awaiting confirmation

Guest Fields

Each reservation contains one or more guests. The first_name field is always present, falling back to "Guest" when the source system does not provide a name.

Field	Type	Required	Description
`first_name`	string	Yes	Guest first name (fallback: "Guest")
`last_name`	string	No	Guest last name / surname
`email`	string	No	Email address (normalized to lowercase, accents stripped)
`phone`	string	No	Phone number (normalized to E.164 format when possible)
`date_of_birth`	string	No	Date of birth (YYYY-MM-DD)
`nationality`	string	No	ISO 3166-1 alpha-2 country code
`gender`	string	No	Gender: "male", "female", or "other"
`language`	string	No	Preferred language (ISO 639-1 code)
`document_type`	string	No	Identity document type (see below)
`document_number`	string	No	Identity document number
`opt_in_status`	string	No	Marketing consent: "opted_in", "opted_out", or "pending"

Document Types

Document type codes from source systems are normalized to these canonical values.

passport

Passport

national_id

National identity card

drivers_license

Driver's license

other

Stay Fields

Stays represent individual room assignments within a reservation. A single reservation can span multiple rooms or room moves.

Field	Type	Required	Description
`start_date`	string	No	Stay start date (YYYY-MM-DD)
`end_date`	string	No	Stay end date (YYYY-MM-DD)
`room_type`	string	No	Room type name (e.g., "Double", "Suite")
`board_type`	string	No	Board type code (see below)
`rate_code`	string	No	Rate plan code
`adults`	number	No	Number of adults
`children`	number	No	Number of children
`babies`	number	No	Number of babies / infants

Board Type Codes

Board types from source systems are normalized to these short codes.

RO

Room Only

BB

Bed & Breakfast

HB

Half Board

FB

Full Board

AI

All Inclusive

Charge / Extra Fields

Extras represent additional charges and services beyond the base room rate, such as spa treatments, minibar, or restaurant charges.

Field	Type	Required	Description
`code`	string	No	Service or charge code
`name`	string	No	Service or charge description
`amount`	number	No	Charge amount
`quantity`	number	No	Quantity (minimum: 0)

Timestamps

Hotelinking normalizes various date and timestamp formats from source systems into consistent ISO 8601 formats.

Date fields use YYYY-MM-DD format (e.g., 2026-03-15).

Timestamp fields use YYYY-MM-DDTHH:mm:ssZ format with UTC timezone (e.g., 2026-03-15T14:30:00Z).

Source systems may provide dates in different formats (DD/MM/YYYY, timestamps with local timezones, etc.). Hotelinking handles conversion automatically during the parsing step.

Example Payload

A complete reservation object after normalization. This is the structure delivered to destination systems.

canonical reservation

{
  "reservation_id": "R-2026-00451",
  "confirmation_number": "CONF-78234",
  "hotel_id": "HTL-001",
  "hotel_name": "Grand Marina Resort",
  "check_in": "2026-03-15",
  "check_out": "2026-03-18",
  "booking_date": "2026-02-20",
  "status": "confirmed",
  "channel": "direct",
  "market_segment": "Leisure",
  "nights": 3,
  "amount": 750.00,
  "amount_net": 712.50,
  "currency": "EUR",
  "external_created_at": "2026-02-20T10:30:00Z",
  "external_updated_at": "2026-02-21T08:15:00Z",
  "guests": [
    {
      "first_name": "Maria",
      "last_name": "Garcia",
      "email": "maria.garcia@example.com",
      "phone": "+34612345678",
      "date_of_birth": "1985-06-12",
      "nationality": "ES",
      "language": "es",
      "document_type": "national_id",
      "document_number": "12345678A",
      "opt_in_status": "opted_in"
    }
  ],
  "stays": [
    {
      "start_date": "2026-03-15",
      "end_date": "2026-03-18",
      "room_type": "Double Sea View",
      "board_type": "HB",
      "rate_code": "BAR",
      "adults": 2,
      "children": 0,
      "babies": 0
    }
  ],
  "extras": [
    {
      "code": "SPA-001",
      "name": "Spa Treatment",
      "amount": 85.00,
      "quantity": 1
    }
  ]
}

Field Mapping

How raw API responses are parsed and mapped to these canonical fields.

REST API

Complete reference for all available API endpoints.