REST API Integration

Expose a REST API and Hotelinking will pull reservation data on a schedule.

How It Works

Hotelinking connects to your API using scheduled cron jobs, typically every 15 to 60 minutes. Each execution follows a five-step process:

Authenticate

Connects to your API using your configured credentials (API key, Bearer token, Basic auth, OAuth2, HMAC, or custom header).

Fetch data

Calls your endpoint with date range filters to retrieve reservations for the target window.

Parse response

Extracts records from the response using configured field mappings and transforms your data into the canonical schema.

Normalize and transform

Applies normalization (phone numbers, names, emails) and business logic transforms to ensure data quality.

Deliver

Sends the processed records to the configured destination system (CRM, marketing platform, or data warehouse).

Endpoint Requirements

Your API should expose at minimum a list endpoint that returns reservations filtered by date range.

Required capabilities

JSON responses

Return reservations as JSON, either as an array or wrapped in a root object.

Date range filtering

Support date range parameters such as dateFrom and dateTo.

Nested data

Include guest, stay, and charge data nested within each reservation record.

Recommended capabilities

Single-record lookup endpoint (by reservation ID)
Pagination for large result sets (cursor or offset-based)
Filter by reservation status (confirmed, checked-in, checked-out, cancelled)

Example: List Reservations Endpoint

Below is a sample request and response showing the expected structure.

GET/api/reservations

Query Parameters

dateFrom (required) — Start of the date range (ISO 8601)
dateTo (required) — End of the date range (ISO 8601)
status (optional) — Filter by reservation status

request

GET /api/reservations?dateFrom=2026-01-01&dateTo=2026-01-07&status=confirmed
Authorization: Bearer YOUR_API_KEY

response — 200 OK

{
  "reservations": [
    {
      "id": "RES-12345",
      "confirmation_number": "CONF-98765",
      "check_in": "2026-01-15",
      "check_out": "2026-01-18",
      "booking_date": "2025-12-20",
      "status": "confirmed",
      "channel": "direct",
      "source": "website",
      "total_amount": 450.00,
      "currency": "EUR",
      "guests": [
        {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "phone": "+34612345678",
          "date_of_birth": "1985-03-15",
          "nationality": "ES",
          "document_type": "P",
          "document_number": "AB123456",
          "marketing_consent": true
        }
      ],
      "rooms": [
        {
          "room_type": "Double Superior",
          "board": "half_board",
          "rate_code": "BAR",
          "start_date": "2026-01-15",
          "end_date": "2026-01-18",
          "adults": 2,
          "children": 0
        }
      ],
      "charges": [
        {
          "code": "SPA",
          "description": "Spa Treatment",
          "amount": 75.00,
          "quantity": 1
        }
      ]
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 50
}

Expected Response Codes

Your API should return standard HTTP status codes so Hotelinking can handle retries and errors correctly.

Code	Meaning	When to return
200	OK	Request succeeded. Return the reservation data.
400	Bad Request	Invalid parameters (e.g. malformed date, missing required param).
401	Unauthorized	Invalid or expired credentials. Hotelinking will re-authenticate.
404	Not Found	Endpoint or resource does not exist.
429	Too Many Requests	Rate limit exceeded. Include a `Retry-After` header (seconds).
500	Server Error	Unexpected error. Hotelinking will retry with backoff.

Content Type

All responses must include the header Content-Type: application/json and return valid JSON. The response body should be UTF-8 encoded.

Single Record Endpoint (Optional)

If your API supports fetching a single reservation by ID, Hotelinking can use it for targeted lookups and data enrichment.

GET/api/reservations/{reservation_id}

Path Parameters

reservation_id (required) — The reservation identifier

response — 200 OK

{
  "id": "RES-12345",
  "confirmation_number": "CONF-98765",
  "check_in": "2026-01-15",
  "check_out": "2026-01-18",
  "status": "confirmed",
  "guests": [...],
  "rooms": [...],
  "charges": [...]
}

POST-Based Endpoints

Some PMS systems use POST requests with parameters in the request body instead of query strings. Hotelinking supports both approaches.

POST request example

POST /api/reservations/search
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "date_from": "2026-01-01",
  "date_to": "2026-01-07",
  "property_id": "HOTEL-001",
  "include": ["guests", "rooms", "charges"],
  "status": ["confirmed", "checked_in"]
}

Whether your API uses GET or POST, Hotelinking adapts to your conventions. Provide your API documentation during onboarding and we will configure the request format accordingly.

Response Format

JSON only

XML and SOAP responses are not natively supported. If your system only produces XML, contact us to discuss a custom adapter.

Root path extraction

If your array is wrapped in a root object (e.g. { "reservations": [...] }), we configure a root_path to extract the data automatically.

Nested objects

Guests, stays/rooms, and charges can be nested within each reservation record. Hotelinking will parse nested arrays and map fields at each level.

Flat responses

If your API returns flat records (one row per guest per stay), Hotelinking can flatten and deduplicate to reconstruct reservation objects.

Date Filtering

Date range filtering is essential for efficient data synchronization. Hotelinking uses three sync types per integration, each targeting a different date window.

Pre-Stay

Reservations with future check-in dates. Used for pre-arrival communications and upselling.

Stay

Currently checked-in guests. Used for in-stay engagement and real-time guest profiles.

Post-Stay

Reservations with past check-out dates. Used for feedback requests and loyalty programs.

Keep date ranges tight

Always pass both dateFrom and dateTo parameters. Keep ranges between 1 day and 1 week to avoid timeouts. APIs that return unbounded result sets are a common source of failures.

Pagination

If your API returns paginated results, Hotelinking will automatically follow pages until all records are retrieved.

Cursor-based

Return a next_cursor token in the response body. Hotelinking passes it back in the next request to retrieve the following page.

Offset-based

Support offset and limit query parameters. Hotelinking increments the offset until the returned page is empty or smaller than the limit.

Rate Limiting

Hotelinking includes built-in retry logic and respects standard rate limiting conventions.

Automatic retry

If your API returns 429 Too Many Requests, Hotelinking will wait for the duration specified in the Retry-After header before retrying.

Call frequency

Typical polling frequency is every 15 to 60 minutes, per brand, per sync type. A property with all three sync types active will receive approximately 3 to 12 API calls per hour.

Circuit breaker protection

If your API returns consecutive errors, Hotelinking will automatically pause requests to avoid overwhelming a failing system. The circuit breaker resets after a configurable cooldown period.

Authentication Methods

Hotelinking supports the following authentication methods. The method is configured per integration and applied automatically to every request.

Bearer Token

Sends your API key in the Authorization: Bearer header.

API Key

Sends a key in a custom header or query parameter (e.g. X-API-Key).

Basic Auth

HTTP Basic authentication with username and password.

OAuth 2.0

Client credentials or authorization code flow with automatic token refresh.

HMAC Signature

HMAC-SHA256 or HMAC-SHA512 request signing using a shared secret.

Custom Header

Credentials injected into the request body or custom headers for non-standard authentication schemes.