Step-by-Step Flow of API Calls
The normal flow of API calls from TripAdvisor to the Connectivity Partner's endpoint is comprised of four major phases:
- Endpoint Configuration
- Availability Checks
- Checking availability (this could include Hotel Availability, Expanded Availability and Booking Availability (/availability)
- Booking Attempts
There are two API calls that can be made from TripAdvisor to the Connectivity Partner's endpoint to retrieve settings and inventory for the endpoint:
The "/config" API call can be made at any time and must reflect the latest values for the endpoint settings. For example, the emergency contacts or languages.
The "/hotel_inventory" API call is made daily and must reflect the full inventory list supported by the Connectivity Partner.
Note: This "/hotel_inventory" API call is only required for Internet Booking Engines and not required if an inventory/bidding feed is already configured with TripAdvisor.
Retrieving availability data for properties serve the purpose of presenting the information directly to travelers using the TripAdvisor site as they research, plan and prepare to book their trip:
- Checking availability, this could include Hotel Availability, Expanded Availability and Booking Availability (/availability)
These availability results will then be displayed to the traveler. The traveler will select one of the available rooms and provide their name, address and payment information.
This leads to the next phase of the API call flow, the booking attempt.
There are four API calls that fall into the booking attempts phase, as follows:
- Submitting a booking for a room (/booking_submit). (Requires HTTPS.)
- Verifying that the booking was successful (/booking_verifiy). (Requires HTTPS.)
- Cancellation of a booking (/booking_cancel). (Requires HTTPS.)
- Subsequent updates to booking status (/booking_sync). (Requires HTTPS.)
As previously mentioned, when the traveler decides on a room at a property, they will enter their details into a booking form on the TripAdvisor site:
This information will then be transmitted using the "/booking_submit" API call to request a booking from the Connectivity Partner's endpoint.
If a successful hotel booking is processed on the Connectivity Partner's system, the reservation details (including a unique "reservation id") will be returned:
Using the "reservation id", TripAdvisor will send a follow up request (the "/booking_verify" API call) to ensure the booking was successfully made.
The booking will now appear in the traveler's "My Bookings" page on TripAdvisor, and in the Connectivity Partner's system so that the hotel can account for it.
Later, if the traveler chooses to cancel the booking (within the cancellation policy), they can do this through their TripAdvisor "My Bookings" page. This provides a high level of convenience and usability to the traveler.
The "/booking_cancel" API call allows this functionality for the traveler.
Alternately, if a traveler cancels directly with the hotel, when TripAdvisor sends the "/booking_sync" API call the response can be used by the Connectivity Partner to provide TripAdvisor with this update to the status of the booking — so that no commission will be charged for it.
If you wish to become an integrated Connectivity Partner with TripAdvisor, you must complete the following steps.
For the following steps you will need your unique 15 character ID that was sent to you via email when you registered to become a Connectivity Partner. If you cannot locate your ID, please email firstname.lastname@example.org to retrieve it. If you have not registered yet, please visit https://www.tripadvisor.com/ConnectivityPartnerSignup.
Instant Booking Implementation
- Implement the TripConnect (Hotel Availability Check) API : Use the documentation of the Hotel Availability Check (HAC) API to complete a HAC API implementation for your site. This includes all three responses: Configuration, Inventory, and Availability. TripAdvisor offers a test site you can use while developing. This site will make different HAC API calls and allow you to verify the results. It will also provide helpful feedback if it encounters problems with your implementation.
- Implement the Instant Booking API : Use the documentation of the Instant Booking API to complete a Instant Booking API implementation for your platform. In addition to the HAC API responses above, this includes: Availability, Booking, and Verification, and if supported Cancel and Sync. TripAdvisor offers a test site you can use while developing. This site will make different Instant Booking API calls and allow you to verify the results. It will also provide helpful feedback if it encounters problems with your implementation.
- API Endpoint Submission: Once you have finished building your API, visit the API Submission site to complete our integration testing process. Please note: It is recommended that you use test hotels during this process as the tool will book live reservations.
You must use this link to submit your production endpoint for approval.
If you fail any of the tests, you will need to fix the issues before you can proceed to the next test.
- Important: You must provide your full inventory and remove all test properties for us to consider your implementation complete.
- Quality Assurance: Once you have completed the above steps, your endpoint will be submitted to our quality assurance team.
They will conduct further testing before your endpoint can be approved. Once the quality assurance team has approved your API implementation, you will receive an email confirming that you have completed this step.
We require all our instant booking partners to be PCI compliant. We will need to whitelist all booking endpoints that we connect with to our CDE (Credit Card Data Environment) in order for us to do this we will need a copy of your PCI DSS Attestation of Compliance (AOC).
- Inventory Matching: Once approved, an automated process at TripAdvisor will download your hotel inventory from your endpoint.
This process will attempt to match your hotels to TripAdvisor hotels. All unmatched hotels will go into a separate queue to be reviewed manually, which may prevent your hotels from being able to use TripConnect. You can help the matching process by ensuring that both the hotel name and address are accurate.
- Availability Checks: The second automated process that is run after API Approval performs availability checks across your full inventory. This is to ensure that all your properties can seamlessly activate their TripConnect campaigns (including instant booking) when you have been certified.
- Alpha Testing: The next step is to make bookings for real hotels in the production environment.
To do so, we ask that you provide the details of between 1 and 5 hotels that we can work with in this pilot phase.
- Please note that Certification (and listing on the Connectivity Partners page) is only available on sucessful completion of this Alpha Testing.
The team makes the following reservations (we ask the hotels for preferred booking dates so as not to disrupt their activity):
- single night stay / double occupancy
- two night stay / double occupancy
- if multi-room reservations are supported: 1 night / two rooms / triple occupancy
- Certification Confirmation: Once you have completed the steps listed above, you will become a certified partner. You will receive instructions on how to download marketing materials and PR templates to promote your certification status to hotel partners.
Further information can be found here: FAQs for Connectivity Partners
Migrating to the latest API version
- Testing: Once you have finished building the latest API version, visit the API Submission site to complete the testing process. Please note: It is recommended that you provide test hotel IDs in the "List of hotel test Ids” field so the booking_submit calls are made against these properties during this process as the tool books live reservations.
If you fail any of the tests, you will need to fix the issues before you can proceed to the next test.
- Important: For support please contact email@example.com. If your production endpoint url has changed it will need to be re-whitelisted which is dependent on a weekly release cycle.
- Quality Assurance: Once you have completed the above steps, we will conduct further testing before your migration to the latest API version can be approved.
- Production testing: We will make a test booking for a property already live on instant booking through your connectivity. Please indicate a suitable property with free cancellable rooms. During production testing, we will temporarily pause your instant booking traffic. We anticipate this taking no more than 48 hours.
- Confirmation: After successful testing, we will send you a confirmation and instant booking traffic to your endpoint will be re-enabled.
All Instant Booking API requests from TripAdvisor are sent as a HTTP GET (configuration and inventory) or HTTP POST (availability) request. All parameters will be application/x-www-form-urlencoded, except for the booking_submit, booking_cancel, and booking_sync requests in which case the Content-Type will be set to application/json.
All responses must conform to the JSON specification and be sent with the HTTP Content-Type header set to application/json.
All responses must use UTF-8 encoding.
All responses must return status code 200 (success). Any other status code is not acceptable. This includes status in the 300s (which indicates redirection), 400s (which indicates client error), and 500s (which indicates server error).
Responses must not redirect to another URL. All the URLs in the API below do not use a trailing slash and you cannot redirect to a URL that contains one.
JSON Data Types
There are a few datatypes used throughout this API.String -
- Most values are strings. Strings must have quote marks around them. As stated above, empty strings are unacceptable for optional fields. Do not use control characters like \r, \n, or \t in Strings.
- A number can be used to represent anything from a TripAdvisor ID to a price. Numbers should not have quotes around them. Numbers can also have decimal points if needed
- Can only be the word true or false. Booleans are not written in quotes.
Your API needs to perform at a certain speed in order to handle TripAdvisor traffic. Responses to requests can take no longer than 10 seconds on average. The Hotel Inventory Response should take no more than 10 minutes to respond.
Additional Parameters in TripAdvisor Requests
TripAdvisor may add new parameters to its API requests at future dates. Those may not be documented at the time of your implementation so you should not validate against new parameters. These newly released parameters should not cause your API to return errors.