XML Integration Guide for Hotel Booking APIs [Technical Guide]

Why API Integration Is Now a Baseline Requirement

A decade ago, API integration for hotel booking was a competitive advantage. Today, it is the baseline cost of operating at scale. Agencies handling more than a few hundred bookings per month cannot afford to manage them through manual portal entry — the error rate, the labor cost, and the speed disadvantage are all prohibitive.

This guide is for the technical team or lead developer at a travel agency preparing to integrate a hotel booking API for the first time, or evaluating a migration from an existing integration. It covers the fundamental concepts, the practical implementation steps, and the specific pain points you'll encounter in hotel API integrations.

---

API Format Options: REST, SOAP, and XML-over-HTTP

Before writing a single line of code, you need to understand what format the supplier's API uses. There are three main paradigms in the hotel booking API world:

REST / JSON (Modern Standard)

RESTful APIs with JSON payloads are the current industry standard for new API development. If a supplier built or rebuilt their API in the last 5–7 years, it is likely REST/JSON.

Characteristics:

• HTTP methods: GET for queries, POST for bookings, DELETE or POST for cancellations
• Payloads: JSON (lightweight, easy to parse in any modern language)
• Authentication: Typically API key in headers or OAuth 2.0 bearer tokens
• Documentation: Usually Swagger/OpenAPI spec available

Advantages: Easier to develop against, faster development cycle, widely supported by modern frameworks.

SOAP / XML (Legacy but Still Common)

SOAP (Simple Object Access Protocol) is an older protocol that wraps XML payloads in a standardized envelope structure. Many major hotel suppliers — including some that process billions in bookings annually — still run SOAP APIs because their infrastructure was built in the 2000s and migration is expensive.

Characteristics:

• Single endpoint URL (all operations POST to the same URL)
• Payloads: XML with SOAP envelope wrapper
• Authentication: Username/password in SOAP header (WS-Security) or custom tokens
• Documentation: WSDL files (Web Services Description Language)

Advantages: Mature, well-defined contracts, built-in error handling via SOAP Fault.

Disadvantages: Verbose XML payloads, more complex to implement, requires XML parsing.

XML-over-HTTP (Hybrid)

Some suppliers use a hybrid approach: XML payloads but without the full SOAP envelope structure. This is technically just HTTP POST with XML body.

Characteristics:

• Similar to SOAP structurally but without WS-Security overhead
• Common in travel industry-specific standards (OTA XML schema)
• Often uses OpenTravel Alliance (OTA) message formats

---

Authentication: Getting Access Before You Can Book

Every API requires authentication. The method varies by supplier:

API Key Authentication (Most Common for REST)

GET /api/v1/hotels/search
Headers:
  Authorization: Bearer YOUR_API_KEY_HERE
  Content-Type: application/json

Keys are typically issued per agency account. Treat them as passwords — never expose them in client-side code, never commit them to version control. Store them in environment variables.

HMAC Signature Authentication

Some suppliers require HMAC-signed requests, where you construct a signature from the request parameters + a shared secret + a timestamp:

signature = HMAC-SHA256(secretKey, method + timestamp + endpoint + bodyHash)

The server validates the signature on every request. This prevents replay attacks. If your timestamp is more than 60–300 seconds off from the server's clock, requests will fail — ensure your server's NTP synchronization is correct.

Username/Password in SOAP Header

<soap:Header>
  <wsse:Security>
    <wsse:UsernameToken>
      <wsse:Username>YOUR_USERNAME</wsse:Username>
      <wsse:Password>YOUR_PASSWORD</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

---

The Core Booking Flow

A complete hotel booking through an API follows a consistent flow regardless of the specific supplier:

1. Search (Availability Request)

You submit a search with: destination, check-in date, check-out date, room configuration (adults/children/rooms), and any filters (star rating, property type, etc.).

Sample REST search request:

POST /api/v1/hotels/search
{
  "destination": {
    "type": "city",
    "code": "IST"
  },
  "checkIn": "2026-07-15",
  "checkOut": "2026-07-18",
  "rooms": [
    {
      "adults": 2,
      "children": 0
    }
  ],
  "currency": "USD",
  "nationality": "GB"
}

Key parameters to understand:

• nationality affects pricing in some suppliers (nationality-specific rates exist for many Turkish hotels)
• currency determines the rate currency returned; always clarify if the rate is net or with markup applied
• Some APIs return rateKey or bookingCode — a token that locks the price for a short window (typically 15–30 minutes)

2. Rate Details / Pre-book

Before confirming a booking, most APIs provide a "pre-book" or "price check" step that validates the rate key and returns the full cancellation policy, any mandatory hotel fees, and final total price.

This step is critical. Never skip it. Rates can change between search and book, and the pre-book step reveals:

• Whether the rate is still available at the searched price
• The precise cancellation policy (free cancellation until X date, non-refundable, etc.)
• Any included board (breakfast, half-board, all-inclusive)
• Mandatory supplements (city tax, resort fee, etc.)

3. Booking Confirmation

Submit the booking with guest details, payment (or payment reference if on credit terms), and the validated rate key.

Sample booking request:

POST /api/v1/hotels/book
{
  "rateKey": "RATE_TOKEN_FROM_SEARCH",
  "holder": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "phone": "+44123456789"
  },
  "rooms": [
    {
      "paxes": [
        {"type": "AD", "firstName": "John", "lastName": "Smith"},
        {"type": "AD", "firstName": "Jane", "lastName": "Smith"}
      ]
    }
  ],
  "clientReference": "AGENCY-REF-2026-001",
  "remark": "Late check-in expected, arriving after 23:00"
}

The response includes a booking reference from the supplier's system. Store this alongside your internal reference. Both are needed for any future modifications or cancellations.

4. Booking Retrieval

Most APIs allow you to retrieve a booking by reference to check its current status. Implement this for your agency's operational workflow — your staff should be able to pull booking details, cancellation policy, and hotel contact information from your system.

5. Cancellation

Cancellation requests require the supplier's booking reference. The API returns the status of the cancellation and any applicable cancellation fee.

POST /api/v1/hotels/cancel
{
  "bookingReference": "HTL-2026-XXXXX",
  "cancellationReason": "Client request"
}

Always capture and store the cancellation reference returned. It is your proof of cancellation for any refund disputes.

---

Error Handling: The Most Underestimated Part

API integrations that handle the happy path correctly are not done. Production-grade integrations handle errors correctly. Common error categories in hotel APIs:

Rate No Longer Available (Price Change)

The rate key has expired or the price has changed. Response:

{
  "error": "RATE_CHANGED",
  "code": 1003,
  "message": "The rate for this selection has changed. New rate: $135.00",
  "newRateKey": "NEW_RATE_TOKEN"
}

Handling: Present the new rate to the agent for approval before proceeding, or automatically accept if within an acceptable variance threshold.

Sold Out

The property or room type has sold out between search and book. Response will indicate no availability. Handling: Redirect to a re-search or offer alternative properties.

Validation Errors

Guest name format, date format, or missing required fields. These are development-time errors that should be caught in testing. Handling: Clear error messages to the agent interface; log the full request/response for debugging.

Timeout and Network Errors

Hotel APIs — especially legacy SOAP ones — can have response times of 5–15 seconds. Implement:

• Request timeout of 30 seconds (hotel API searches often take 10–20 seconds)
• Retry logic for transient network failures (use exponential backoff: retry after 1s, 2s, 4s)
• Circuit breaker pattern: if the API is consistently failing, stop hammering it and surface a clear error

Authentication Failures

API keys that have expired or been rotated. Implement monitoring that alerts you when authentication failures appear in logs.

---

Rate Mapping and Property Matching

One of the less-discussed challenges in multi-supplier hotel integrations is rate mapping — ensuring that "Hilton Istanbul Bomonti" in Supplier A's system is the same property as "Hilton Bomonti Istanbul" in Supplier B's system.

The Problem

Different suppliers use different property codes, different name formats, and different address conventions. If you're aggregating multiple suppliers, you need to deduplicate and normalize.

Approaches

1. GIATA mapping: GIATA is an industry standard for matching hotel property codes across systems. Many large suppliers and aggregators support GIATA mapping.
2. Google Places API matching: Use lat/lon + place name matching to normalize properties. Works well but requires ongoing maintenance.
3. Manual curation: For a focused set of core properties (e.g., top 300 Istanbul hotels), manual curation is worth doing for quality.

For a single-supplier integration, this problem doesn't exist. It becomes critical when integrating two or more suppliers.

---

Sandbox Testing: What to Validate

Every serious supplier provides a sandbox environment. Use it extensively before going anywhere near production. Your test plan should include:

Search Tests

• Single room, 1 adult, 1 night — baseline search
• Multi-room search (5 rooms, groups baseline)
• Long-stay search (14+ nights)
• Search with children (verify child age handling)
• Search with nationality filter
• Search returning zero results (handle gracefully)
• Search for sold-out destination (return handled)

Pre-book Tests

• Valid rate key — confirm details returned
• Expired rate key — confirm error returned and handled
• Rate change — confirm new price surfaced

Booking Tests

• Successful booking — confirmation reference stored
• Booking with special characters in guest names (umlauts, Arabic characters)
• Booking with remark field
• Duplicate booking detection (sending same request twice)

Cancellation Tests

• Cancel within free cancellation window
• Cancel after deadline (verify cancellation fee reflected)
• Cancel non-existent reference (error handled)

Load and Performance Tests

• Response time under normal load
• Behavior under high concurrency (simulate 20 simultaneous searches)
• Behavior when API is slow (simulate 15-second response time)

---

Rate Caching Strategy

Hotel API searches are slow and expensive (in API call terms, especially for SOAP suppliers). A smart caching strategy is essential:

Search result cache: Cache search results for 15–20 minutes. A user searching for Istanbul hotels doesn't need live-refresh pricing on every page load during a session.

Property data cache: Hotel names, descriptions, facilities, photos, and static information change rarely. Cache these for 24–72 hours. Do not re-fetch on every search.

Rate key validity: Most rate keys expire after 15–30 minutes. Do not cache rate keys across sessions. A new rate key must be generated at pre-book time.

Cache invalidation: If a user modifies search parameters (dates, rooms), always flush the search cache and re-query live rates.

---

Best Practices Summary

• Always use HTTPS — never send credentials or booking data over plain HTTP
• Store booking references redundantly — your internal ID and the supplier's ID in your database
• Log all API requests and responses — for debugging, dispute resolution, and auditing
• Implement monitoring and alerting — know within minutes if your booking API is failing
• Use idempotency keys where the API supports them — prevent duplicate bookings from retry logic
• Validate guest data before sending — format first/last names consistently, validate email, validate phone format
• Handle TLS certificate expiry — supplier APIs sometimes let their certificates expire; your HTTP client should surface clear errors
• Build for supplier outage — have a fallback (manual portal booking) documented for your team

---

Get API Access for Turkey Hotel Inventory

If you're integrating hotel API access for Turkey, Safaryar Holidays provides B2B partners with API access to our Istanbul and Turkey hotel inventory, including direct allotment rates and full ground services.

We support agencies through the technical integration process with documentation, sandbox access, and developer support.

Apply for B2B API Access at Safaryar Holidays →