Core Concepts

Key concepts to understand before integrating with Hotelinking.

Entities

The platform works with four core entity types that represent the fundamental data structures in hospitality systems. All data flowing through Hotelinking is normalized into these canonical types.

Reservation

A booking record with check-in and check-out dates, status, monetary amounts, channel, and source information. The root entity that contains all other data.

Guest

A person associated with one or more reservations. Includes name, email, phone, date of birth, nationality, document details, and marketing opt-in status.

Stay

A room assignment within a reservation. Contains start and end dates, room type, board type (RO, BB, HB, FB, AI), rate code, and occupancy details.

Charge / Extra

A line item attached to a reservation such as minibar, spa services, or tourist tax. Each has a code, name, amount, and quantity.

Entity Relationships

The reservation is the root entity. All other entities are nested within it. When data arrives from your system, Hotelinking expects this hierarchical structure (or will construct it from flat data).

Reservation(root entity)

guests[]One or more guests per reservation

stays[]Room assignments within the booking

extras[]Charges and additional services

Note: Some PMS systems nest guests within stays rather than at the reservation level. Hotelinking automatically flattens and deduplicates guests during processing.

Multi-Tenant Hierarchy

Hotelinking is a multi-tenant platform. Understanding the organizational hierarchy is important for configuring your integration correctly.

Tenant

Your organization -- a hotel chain or management company. All data is isolated per tenant. Credentials for your API are configured at this level and shared across all properties.

Brand

A single hotel property within the tenant. Each brand has an internal brand_id and an external_brand_id which is your system's property identifier. Brand-specific configuration overrides can be applied here.

Integration

The external system being connected -- your PMS or CRS. Defines the available API endpoints, authentication method, and data capabilities. A single integration definition is shared across all tenants that use the same system.

External Brand ID

The external_brand_id is how Hotelinking identifies which property to query in your system. When making API calls, this value is sent as a parameter so your system returns data for the correct hotel.

Data Pipeline

Every piece of data that flows through Hotelinking passes through a standardized processing chain. Here is what happens at each stage.

Fetch

Pull data from your API on a schedule (e.g. every 15 minutes), or receive it via webhook. Hotelinking handles authentication, pagination, and date range filtering automatically.

Parse

Extract records from your API response using configured field mappings. The parser navigates your response structure, maps fields to canonical names, and applies value transformations (e.g. translating status codes).

Normalize

Clean and standardize data. Phone numbers are normalized to international format, names are properly cased, and email addresses are validated and lowercased. Accent marks and special characters are handled.

Transform

Convert the normalized data into the format required by the destination system. This includes computing derived fields (e.g. total amounts from charges), restructuring nested arrays, and applying business logic.

Deliver

Send the processed data to the CRM or marketing destination. Delivery includes retry logic, circuit breakers for unhealthy connections, and detailed execution logs for monitoring.

Environments

Hotelinking supports two environments for every integration. This allows safe development and testing before going live with production data.

Production

Live data with real API calls to your system. Used for active hotel properties with real guest data flowing through the system.

Sandbox

Test environment with mock responses. Safe for development and integration testing. Falls back to mock data when sandbox-specific credentials are not configured.

Testing your integration

We recommend starting in the sandbox environment. You can provide sample API responses and Hotelinking will configure the parser and transformations against that test data before connecting to your live system.