Hotel API Frequently Asked Questions

Introduction

This FAQ addresses common questions about the Hotel JSON API, including both the v11 multi-step workflow and the SearchComplete API (single consolidated endpoint). These questions are organized by topic to help you quickly find the information you need.

API Access and Authentication

Q: How do I get access to the Hotel JSON API?

Contact your Travelport account manager to request access. You'll need to provide your PCC (Pseudo City Code) for provisioning. Your account manager will coordinate setup for both pre-production and production environments.

Q: How does authentication work?

The API uses OAuth 2.0 authentication. You must:

• Obtain OAuth credentials (client_id and client_secret) from Travelport

• Request an access token using the client credentials grant

• Include the Bearer token in all API requests

• Include your PCC in the XAUTH_TRAVELPORT_ACCESSGROUP header Token endpoint for pre-production.

Q: How do I test my credentials?

Test your credentials with a simple API call to the search endpoint. If you receive a 401 error, verify your OAuth token is valid and hasn't expired. Tokens expire after 24 hours.

Q: What should I do if my account is disabled due to inactivity?

Contact Travelport support or your account manager to re-enable your account. You may need to reset your password through the provided reset link.

Q: How do I access SearchComplete API?

SearchComplete is available to all Hotel JSON API customers. Use the same authentication as v11. For pre-production testing, ensure your PCC is provisioned for SearchComplete access.

API Endpoints and Usage

Q: What's the difference between v11 and SearchComplete?

Recommendation: Use SearchComplete for new implementations. It's simpler, faster, and recommended by Travelport.

Q: Does SearchComplete support all v11 functionality?

Yes. SearchComplete returns the same data as the combined v11 search, availability, and rules responses. It includes property details, available rates, room types, pricing, and rate rules including cancellation policies.

Q: Can I use both v11 and SearchComplete in the same application?

Yes, but it's not recommended. Pick one workflow and use it consistently. SearchComplete is the recommended approach for all new development.

Q: Are all transactional endpoints available in SearchComplete?

SearchComplete currently handles search, availability, and rules. For booking operations (create, retrieve, modify, cancel), use the standard booking endpoints which work with both v11 and SearchComplete results.

Q: How does pagination work?

Large search results are paginated automatically. The response includes a pagination object with a nextIdentifier. Use the GET request to retrieve additional pages.

Search and Availability

Q: How do I search by location?

You can search by:

• IATA airport or city code (e.g., "SFO")

• City name and country (e.g., "San Francisco", "US")

• Geographic coordinates with radius (latitude, longitude, radius in miles)

• Specific property IDs

Q: What's the maximum search radius?

The current maximum is 25 miles. If you need a wider radius, contact your account manager to discuss your use case and potential enhancements.

Q: How many properties can I search at once?

You can search for specific properties by ID without a strict limit, but for performance, batch requests in groups of 20-25 properties. For location-based searches, the API returns available properties within the specified area.

Q: Should I set returnOnlyAvailableProperties to true?

Yes, unless you specifically want to see properties without availability. Setting this to true filters results to only show properties that have available rooms for your dates, improving relevance.

Q: Are search results cached?

SearchComplete includes intelligent caching to improve performance. You can control caching behavior using the TVP-Cache-Control header. Use "no-cache" for real-time pricing (slower but most current), or omit the header to use cached results when available (faster).

Q: How current are the rates in search results?

For cached results, rates are typically fresh within the last few minutes. For real-time rates, use TVP-Cache-Control: no-cache. Always make a final price check before booking.

Booking and Reservations

Q: How do I create a booking?

To create a booking, you need:

• propertyKey - From the search response

• rateKey - From the selected rate in search results

• Guest details - Name, contact information

• Payment information - Credit card or guarantee details

• Rate rules acknowledgment - Confirm cancellation policies

Use POST /book/reservations with this information.

Q: How do I handle multi-room bookings?

Include multiple offers in a single booking request, where each offer corresponds to a specific room and rate. Each room must have at least one traveler associated with it.

Q: Can I attach a hotel booking to an existing PNR?

Travelport is working on supporting record locator references in booking requests. Contact your account manager for the current status and availability timeline for this feature.

Q: What does "Hotel sell unconfirmed from supplier" mean?

This error indicates the hotel could not confirm the booking. Common causes include:

• Property is no longer available for those dates

• Rate has expired or changed

• Room type is sold out

• Payment or guarantee information issue

Verify your booking parameters and try again with fresh search results.

Q: How do I retrieve a booking?

Use GET /book/reservations/{confirmationId} where confirmationId is the confirmation number returned when the booking was created.

Q: How do I modify or cancel a booking?

Modifications: Use PUT /book/reservations/{confirmationId} with updated details.

Cancellations: Use DELETE /book/reservations/{confirmationId}. The response will include any applicable cancellation penalties based on the rate rules.

Q: Where can I find cancellation policies before booking?

Cancellation policies are in the rate.rateRules.cancelPolicy object in search results. This includes the cancellation deadline and any penalty amounts. Always display this information to users before booking.

Q: Why am I getting "GUARANTEE TYPE HAS BECOME GUARANTEE REQUIRED" errors?

What's Happening:

Your sell requests are currently structured in a way that causes them to fail for guarantee-required rates:

• The "acceptGuaranteeChangeInd" flag is not included in initial requests

• The Payment object only includes the Amount field

• The guarantee and deposit indicator fields are left unpopulated

• This means every request is treated as if you're requesting a deposit-required rate, regardless of what the availability/rules response actually returned. When the actual rate requires a guarantee instead of a deposit, the booking fails.

• We can see that you're successfully rebooking by resending with "acceptGuaranteeChangeInd" = true, but this workaround doubles your transaction volume and creates unnecessary errors.

The Solution:

The Payment object includes two boolean fields (guaranteeInd and depositInd) that must be populated based on the rate information in your availability or rules response.

Correct Implementation:

For guarantee-required rates:

[
 {
  "Amount": {
   "code": "EUR",
   "value": 120
  },
  "guaranteeInd": true,
  "depositInd": false
 }
]

For deposit-required rates:

[
 {
  "Amount": {
   "code": "EUR",
   "value": 120
  },
  "guaranteeInd": false,
  "depositInd": true
 }
]

Rates and Pricing

Q: What's included in the total rate?

The rate breakdown includes:

• base - Base room rate

• totalTaxes - All applicable taxes

• totalFees - Hotel fees (resort fees, service charges, etc.)

• total - Complete amount customer pays (base + taxes + fees)

Q: Can I get nightly rate breakdowns?

Yes. Set returnCompleteNightlyRateBreakdown: true in your search request. This returns per-night pricing in the nightlyRates array.

Q: Why do some rates show zero dollars?

Zero-dollar rates occasionally appear due to promotional rates or backend data issues. These should typically be filtered out or confirmed with Travelport before displaying to users.

Q: How do I filter by rate category (Corporate, Government, etc.)?

Use the propertyFilter.categories array in your request. Example: ["CORPORATE", "GOVERNMENT"]. This filters results to only show rates matching those categories.

Q: What's the difference between deposit and guarantee?

• Deposit: Payment required in advance, typically non-refundable or with restricted refund policies.

• Guarantee: Hold on credit card or payment method, charged later (usually at check-in or checkout). May be fully refundable if cancelled before deadline.

Check rateRules.depositPolicy and rateRules.guaranteePolicy for specific requirements.

Q: What's the maximum booking window?

Booking windows vary by hotel and rate. If you receive "Travelport rates are unavailable for the property," you may be searching too far in advance. Most hotels support bookings up to 11-12 months ahead.

Hotel Data and Content

Q: How do I get hotel amenity codes for icon mapping?

Contact your Travelport representative to request an export of all amenity codes. This includes standard codes (pool, gym, WiFi, etc.) that you can map to icons in your UI.

Q: How many properties are available through Travelport?

Travelport provides access to approximately 140,000 properties worldwide, with about 100,000 shared with major OTAs. Content includes aggregated inventory from multiple sources including Booking.com.

Q: Are hotel descriptions and images included?

Yes. Set propertyFilter.returnAllImageURLs: true and propertyFilter.imageSize to "LARGE" (or "SMALL", "MEDIUM") to control image quality. Property descriptions, amenities, and images are included in the search response.

Q: Can I get specific amenity details like check-in times or security policies?

Detailed amenity information depends on what the property provides. Standard amenities are included, but specific policies may require accessing the property details or contacting the hotel directly.

Q: What does "availability": "Other" mean?

Properties with availability "Other" may have limited availability or conditional booking rules. If this differs from "Open" status in your testing, discuss with Travelport whether these properties should be treated differently in your UI.

Performance and Optimization

Q: How many concurrent requests can I make?

For optimal performance, make 3-5 concurrent requests. Travelport is expanding cache support and load handling capabilities. Contact your account manager if you need higher concurrency limits.

Q: What's the best way to search a large list of properties?

For 50+ properties:

• Batch requests into groups of 20-25 properties

• Make concurrent requests (3-5 at a time)

• Use caching where appropriate

• Consider using location-based search instead of property IDs if applicable

Q: Should I cache search results?

Yes, for browsing experiences. Cache results for a few minutes to improve performance. Always make a fresh no-cache request before final booking to ensure current pricing.

Q: How can I improve response times?

• Use SearchComplete instead of v11 (1 call vs 3 calls)

• Leverage caching - omit TVP-Cache-Control for faster responses

• Batch property searches appropriately (20-25 per request)

• Use concurrent requests within recommended limits (3-5)

• Request only needed data - use excludeResponseFields to reduce payload size

Error Handling and Troubleshooting

Q: What do I do if I receive a 401 Unauthorized error?

Check the following:

• OAuth token is valid and hasn't expired (tokens expire after 24 hours)

• Authorization header includes "Bearer" prefix

• XAUTH_TRAVELPORT_ACCESSGROUP header contains correct PCC

• Request fresh token if current one expired

Q: What causes "PROPERTY NOT AVAILABLE" errors?

This typically means:

• Property has no availability for the requested dates

• You're searching outside the property's bookable window

• Property information has changed - use fresh search results

• Cache expiration - make request with TVP-Cache-Control: no-cache

Q: How do I handle "Bad Request" errors?

Check the errors array in the response. It includes:

• code - Error code identifying the issue

• message - Human-readable error description

• field - Specific field causing the error (if applicable)

Use this information to identify and fix the issue in your request.

Q: Why do Postman and Swagger show different field names?

There are known discrepancies between Postman examples and Swagger documentation (e.g., "Prefix" vs "Title" in PersonName). Always rely on the Swagger/OpenAPI documentation for the authoritative field mappings.

Q: What if I find issues parsing JWT tokens?

Travelport's OAuth tokens may not conform to standard JWT format. They can contain only two periods instead of the standard three. Handle these tokens as opaque strings rather than parsing them as standard JWTs.

Q: What should I check if my request works in Production but fails in Pre-Prod?

Common causes:

• Different endpoint URLs - verify you're using correct pre-prod URLs

• PCC provisioning differences - ensure PCC is set up in pre-prod

• Feature availability - some features may not be in pre-prod yet

• Contact your account manager to align pre-prod and prod configurations

Q: Where can I find the warnings array?

The warnings array appears at the top level of the response. It contains non-fatal issues like:

• Properties that didn't respond in time

• Partial results due to supplier timeout

• Deprecated field usage

• Rate limitations or restrictions

Always check warnings to understand if results are complete.

Getting Additional Help

Documentation and Resources:

• OpenAPI/Swagger documentation - Available through developer portal

• Postman collections - Contact your account manager for latest version

• Code examples - Available in documentation

• Migration guides - Available for uAPI, GWS, and v11 to SearchComplete

Support Channels:

• Account Manager - For provisioning, access, and business questions

• Travelport Support - For technical issues and troubleshooting

• Developer Portal - For documentation and API specifications

• Integration Team - For implementation guidance and best practices

For urgent issues or production outages, contact Travelport support immediately with your PCC, error details, and request/response examples.

Document Feedback

We value your feedback on this documentation. If you have suggestions for improvements, find errors, or need clarification on any topic, please contact:

• Your Travelport Account Manager

• Travelport Support team

• Developer Portal feedback form

For urgent API issues or production support, contact Travelport support immediately.