Hotel APIs Guide

Use the JSON Hotel APIs to search hotels; retrieve property details, availability and rates; and book a room/s. This guide discusses basic information about what each Hotel request does. Object-level details such as supported formats and values are covered in the Hotel API References.

Related Content: Hotel API References

In this guide:

• Workflow Summary
• Hotel Search
• Hotel Search Pagination
• Hotel Details
• Hotel Availability
• Hotel Availability Pagination
• Hotel Rules
• Create Hotel Reservation
• Modify/Add/Cancel Hotel Reservation
• Hotel Retrieve

Workflow Summary

The following table summarizes all required and optional steps in the hotel booking workflow, and provides links to the API reference for each for additional details.

Step #	Booking Workflow Step	Description and Notes	API Reference
1	Hotel search	Search for hotels, either by location or by one or more property IDs. These requests use pagination, and you can request additional pages of search results.	Hotel Search by ID API Reference Hotel Search by Location API Reference
2 (optional)	Hotel details	Request a detailed description and additional images for one specified property.	Hotel Details API Reference
3	Hotel availability	Check room types and rates at one or more properties. This request uses pagination, and you can request additional pages of availability results.	Hotel Availability API Reference
4 (optional)	Hotel rules	Retrieve the rules associated with a specific rate by sending an offer ID from an Availability response,	Hotel Rules Reference Payload API Reference Hotel Rules Full Payload API Reference
5	Create Reservation	To complete the booking, send the Create Reservation reference payload request, which sends an offer identifier from the Availability response, plus traveler and payment details.	Create Reservation Reference Payload API Reference Create Passive Reservation Full Payload API Reference

The following diagram shows all required and optional steps in the JSON Hotel API booking workflow.

Each box in the diagram represents one API call in the workflow.

Hotel Search

The Hotel Search API allows you to search for hotels either by location or by one or more property IDs:

• Search by location to search by either geographic coordinate information, or the city, state/province, and country, or the IATA airport or city code.

• Search by property ID/s to search by one or more property IDs.

The search qualifiers include: Dates, Chain Codes, Brand Codes, Negotiated Rate Codes, Distance.

The response returns a list of properties based on either the property list or location sent.

After the search request, you must send an availability request for a specific property per below before booking. If desired, you can send a details request to retrieve a detailed description and images.

Hotel Search Pagination

Hotel Search uses pagination by default. The initial search response returns 25 properties and an identifier to be used for retrieving additional pages, and notes the total number of properties found. Use the GET search pagination request to retrieve each additional page of 25 properties until the end of the list is reached.

The identifier used for pagination is saved for 30 minutes. A new hotel search request must be performed after it expires.

Hotel Details

After a hotel search, you can send the optional Hotel Details request to retrieve a detailed property description and images for one specific property.

Hotel Availability

Hotel Availability returns the room types and rates available at one or more specified properties on specified dates. You can send an Availability request either directly after a Search request, or you can send an optional Details request to retrieve a detailed property description and images.

You can request availability for a single property with minimal rate modifiers, or for up to 10 properties. The request supports multiple rate categories. The response returns a maximum of 100 rates per property per page until all rates are received.

In the v11 release, each rate returned in the response has a unique offer ID value. You can use this offer ID as a reference identifier when either requesting rules for or booking that offer, using a reference payload request for your Rules or Create Reservation request per below.

Hotel Availability supports the following options; see the Hotel Availability API Reference for details:

• Consolidating common offer details: By default, Availability consolidates common information across offers into the ReferenceList object. This can reduce response time by not repeating information in multiple offers. To disable this feature, send the verboseResponseInd indicator set to true to return all details with each offer.

• Maximum response time: Optionally, you can set a timeout value in maxResponseWaitTime to set a length of time to wait for a response. After this time the request times out and returns all properties retrieved at that point

The Availability response returns structured tax and fee details. The tax details returned are specific to each hotel provider. Some hotel providers return only totals and others return full breakdowns. The hotel providers that send the new tax breakdown information are as follows:

• 1G Host Providers: Return Total Taxes, but do not return Total Fee breakdown.

• Marriott chains: Return Total Taxes, but do not return a breakdown.

• Hilton chains: Return Total Taxes, but do not return a breakdown.

• Expedia properties: Return Totals, Taxes, Fees, and breakdowns.

• Booking.com properties: Return Totals, Taxes, Fees, and breakdowns.

Hotel Availability Pagination

Hotel Availability uses pagination by default. The initial availability response returns a maximum of 100 rates per property and an identifier to be used for retrieving additional pages, and notes the total number of rates found. Use the GET availability pagination request to retrieve each additional page of rates per property until the end of the list is reached.

The identifier used for availability pagination is saved for 30 minutes. A new hotel search and/or availability request must be performed after it expires.

Hotel Rules

Hotel Rules is an optional request to return the rules, terms and conditions, and hotel policy information for a specific rate. It can be sent with full reservation details (full payload request) or after an Availability response (reference payload). This information is useful for conveying information such as extra charges and cancellation policies to your customers.

Rules supports the following request formats:

• Full payload request: Request the rules for a rate by sending full offer details including the check-in and check-out dates, rate details, and the booking code from the Availability response.

• Reference payload request: Request the rules for a rate by sending a cached offer ID from the Hotel Availability response.

The rules returned are both informational and actual restrictions or requirements. Different properties can return a different range of rate rules, so the data returned varies based on the chain and property.

Create Hotel Reservation

The Hotel Create Reservation API books a room. Create Reservation supports both of the following request formats:

• Full payload request: Send full offer details including the check-in and check-out dates, rate details, and the booking code from the Availability response, along with traveler, form of payment, and payment information.

• Reference payload request: Send a cached offer ID from the Hotel Availability response, along with traveler, form of payment, and payment information. Sending the cached offer ID also returns more details in Price, Terms and Conditions, and Product.

For either request, the response returns a reservation locator (the PNR), a reservation confirmation, and a supplier locator, which is the confirmation number from the property. The supplier locator can be used to cancel the reservation later if needed. The response also includes the total price and any terms and conditions.

Modify, Add, or Cancel a Hotel Reservation

After booking, you can modify or cancel a reservation as described below, or add another reservation to the booking.

Modify a Reservation

Hotel Modify allows you to modify an existing hotel reservation by changing some or all of the following:

• dates

• payment information

• traveler first and/or last name

• add comments to a reservation

Hotel Modify sends the reservation locator (PNR) of the reservation to modify, and the supplier locator (confirmation number from the supplier). Additional required objects depend on what you are changing:

• To change dates, send the DateRange object with the new dates for the booking.

• To modify payment information, send the FormOfPayment object.

• To modify the traveler name, send Traveler/PersonName with the new given and/or surname.

• To add a comment to an existing reservation, send ReservationComment with the new comment.

You can modify any or all of these objects in the same request.

Add Reservation to PNR

Hotel Add Reservation adds a hotel booking to an existing travel itinerary, or PNR. You must first send Search and Availability requests for the hotel booking you want to make, with an optional Details request between.

Add Reservation supports both of the following request formats:

• Full payload request: Send full offer details including the check-in and check-out dates, rate details, and the booking code from the Availability response, along with receipt, form of payment, and payment information.

• Reference payload request: Send a cached offer ID from the Hotel Availability response, along with receipt, form of payment, and payment information.

Cancel

Hotel Cancel cancels an existing hotel reservation. It requires the record locator and the confirmation number from the Reservation response.

Hotel Retrieve

Hotel Retrieve returns the passenger and hotel reservation information for a requested PNR. It requires the record locator from the Reservation response.