Hotel Booking API

This guide is designed to give a quick start to your integration with the Travelfusion Hotel Booking API. In the XML examples below, various XML elements and attributes have been omitted for simplicity. There are also many more details, features and functions available that you can read about in our XML Request and Reponse Specifications. These specifications also set out specific guidelines concerning how the API should be used and gives various other information that should be read before your integration is completed and released to end users.

The Hotel Booking API provides the following stages:

Details - Select hotel option and get complete information about a hotel
Terms - Submit booking profile (traveller, contact, billing details)
Booking - Commit a booking request
Cancel - Commit a cancellation request

Users may implement the above stages by submiting a number of requests (or commands) to the API in order, as shown in the table below. This table provides a summary; more detailed information is given further in this document.

 Step  Request  Stage  Information  Response
         
 1  StartDetailsHotel  Details  Use this to select hotel option for booking. Also, for every result in the search response, users may retrieve the complete hotel information by initiating this request. This request must contain the RoutingId and OptionId of the desired hotel result.
 StartDetailsHotel
 2  CheckDetailsHotel  Details  Retrieves the hotel details requested in Step 1. Users must repeat this request until an updated router is returned. The frequency of the polling should be no more than 2 seconds. Ideally, as a safety measure, users should use a timeout of 5 minutes. If no router has been returned after the timeout, please report to Travelfusion.  CheckDetailsHotel, if an updated router is returned, users may proceed to the next step (3).
 3  StartTermsHotel  Terms  Submits the booking profile (traveller information, contact details and billing details). At this stage, the API must have 2 items of information.

- The RoutingId of the search. This is supplied in this request.

- The hotel option used for booking. No need for users to supply this; it comes from the last successfully submitted CheckDetailsHotel request.
 StartTermsHotel, includes a unique TFBookingReference that identifies a booking record in the Travelfusion API.
 4  CheckTermsHotel  Terms  Checks the progress of the request in previous step (3). Users must supply the TFBookingReference. Users may repeat this request until the terms stage is complete, i.e. the returned status is not TermsInProgress. The frequency of the polling should be no more than 2 seconds. Ideally, as a safety measure, users should use a timeout of 5 minutes. If the status is still TermsInProgress after the timeout, please report to Travelfusion.  CheckTermsHotel, contains the status of the terms stage. If the status is successful, users may proceed to the next step (5).
 5  StartBookingHotel  Booking  Initiates a booking request. It contains the TFBookingReference.
 StartBookingHotel
 6  CheckBookingHotel  Booking  Checks the progress of the booking initiated in step 5. Users may repeat this request until the booking stage is complete, i.e. the returned status is not BookingInProgress. The frequency of the polling should be no more than 2 seconds. Ideally, as a safety measure, users should use a timeout of 5 minutes. If the status is still BookingInProgress after the timeout, please report to Travelfusion.  CheckBookingHotel, contains the status of the booking stage.
 7  StartBookingCancelHotel  Cancel  Initiates a booking cancellation request. It requires the TF booking reference.  StartBookingCancelHotel
 8  CheckBookingCancelHotel  Cancel  Checks the progress of the cancellation initiated in step 7. Users may repeat this request until the cancellation stage is complete, i.e., the returned status is not CancelInProgress. The frequency of the polling should be no more than 2 seconds. Ideally, as a safety measure, users should use a timeout of 5 minutes. If the status is still CancelInProgress after the timeout, please report to Travelfusion.  CheckBookingCancelHotel

The above commands are explained in detail below.


Step 1: StartDetailsHotel

Once the end user has decided which hotel option they would like to book, a The StartDetailsHotel request should be made to begin the booking process. Multiple requests of this type can be initiated in order to get details of different hotels in the results. However, the Terms stage will initiate a booking for the lastly selected option in this stage. The optional HandoffParametersOnly element must be ommitted or set to false; otherwise, the user will receive a handoff URL.

Request (xml spec detail)

<CommandList>
    <StartDetailsHotel>
        <XmlLoginId>*****</XmlLoginId>
        <LoginId>*****</LoginId>
        <RoutingId>Z1292STFA2LK24T5</RoutingId>
        <OptionId>JBWXSLTXSCBLWKRJ</OptionId>
        <RoomExtraList>
            <RoomExtra roomId="1">
                <ExtraId>CQK7ZSQPHF40DA74</ExtraId>
            </RoomExtra>
        </RoomExtraList>
        <HandoffParametersOnly>false</HandoffParametersOnly>
    </StartDetailsHotel>
</CommandList>

The StartDetailsHotel response may normally be ignored.

Response (xml spec detail)

<CommandList>
    <StartDetailsHotel millis="1">
        <LoginId>*****</LoginId>
        <RoutingId>Z1292STFA2LK24T5</RoutingId>
        <OptionId>JBWXSLTXSCBLWKRJ</OptionId>
    </StartDetailsHotel>
</CommandList>

Step 2: CheckDetailsHotel

The CheckDetailsHotel request retrieves the result of the previous (StartDetailsHotel) request.

Request (xml spec detail)

<CommandList>
    <CheckDetailsHotel>
        <XmlLoginId>*****</XmlLoginId>
        <LoginId>*****</LoginId>
        <RoutingId>Z1292STFA2LK24T5</RoutingId>
        <OptionId>JBWXSLTXSCBLWKRJ</OptionId>
    </CheckDetailsHotel>
</CommandList>

The response may contain an updated Router element with required parameters (like whether date of birth is required per traveller, etc. see a list of hotel parameters here), extra supplier information (terms, credit card requirements, etc.), list of room extras for each room within an option and possibly a supported payment card list (if supplied at this stage).

Once the response contains an updated router, no futher polling will be accepted for the selected hotel. If, subsequently, details for the same hotel are required, users must start over with a new StartDetailsHotel request.

Response (xml spec detail)

<CommandList>
    <CheckDetailsHotel millis="0">
        <LoginId>*****</LoginId>
        <RoutingId>*****</RoutingId>
        <Router>
            <RequiredParameterList>
                <RequiredParameter>
                    <PerRoom>false</ PerRoom> 
                    <Name>DateOfBirth</Name>
                    <DisplayText>Date of birth (dd/mm/yyyy)</DisplayText>
                    <PerPassenger>true</PerPassenger>
                    <IsOptional>false</IsOptional>
                </RequiredParameter>
                <RequiredParameter>
                    <PerRoom>false</ PerRoom>
                    <Name>DateOfBirthIsNotRequiredForAdults</Name>
                    <DisplayText></DisplayText>
                    <PerPassenger>true</PerPassenger>
                    <IsOptional>true</IsOptional>
                </RequiredParameter>
                <RequiredParameter>
                    <PerRoom>true</ PerRoom>    // required per room
                    <Name>GuestName</Name>
                    <DisplayText></DisplayText>
                    <PerPassenger>false</PerPassenger>
                    <IsOptional>false</IsOptional>
                </RequiredParameter>
                ...
            </RequiredParameterList>
            ...
            <ResultList>
                ...
            </ResultList>
            <SupplierInfoList>
                <SupplierInfo>
                    <DisplayName>credit Card as guarantee,not charged</DisplayName>
                    <InfoType>text</InfoType>
                    <Info>the room will be hold the whole night. booking requires a credit card as guarantee, there might be cancellation fees.</Info>
                </SupplierInfo>
                <SupplierInfo>
                    <DisplayName>no credit card as guarantee</DisplayName>
                    <InfoType>text</InfoType>
                    <Info>the customer has to arrive until 6 p.m., at booking time no guarantee like credit card is required, cancellation can be made until 6 p.m. of the arrival day, a cancellation is actually not required.</Info>
                </SupplierInfo>
                   ...
                <SupplierInfo>
                    <DisplayName>Terms and conditions</DisplayName>
                    <InfoType>url</InfoType>
                    <Info>https://www.hrs.com/web3/showCmsPage.do?clientId=ZW5fX05FWFQ-&amp;cid=3-2&amp;pageId=conditions&amp;noBack=true</Info>
                </SupplierInfo>
            </SupplierInfoList>
        </Router>
        <SupplierHandoffData>
            ...
        </SupplierHandoffData>
        <SupportedCardList>
            ...
        </SupportedCardList>
    </CheckDetailsHotel>
</CommandList>

Step 3: StartTermsHotel

The StartTermsHotel request is used to submit the traveller(s), contact and billing details for this booking.

Request (xml spec detail)

<CommandList>
    <StartTermsHotel>
        <XmlLoginId>*****</XmlLoginId>
        <LoginId>*****</LoginId>
        <RoutingId>Z1292STFA2LK24T5</RoutingId>
        <BookingProfile>
            <CustomSupplierParameterList>
                <CustomSupplierParameter>
                    <Supplier>hotelreservationservice</Supplier>
                    <Name>AgentLogin</Name>
                    <Value>jimbo</Value>
                </CustomSupplierParameter>
            </CustomSupplierParameterList>
            <TravellerList>
                <Traveller>
                    <Age>37</Age>
                    <Name>
                        <Title>Mr</Title>
                        <NamePartList>
                            <NamePart>Andy</NamePart>
                            <NamePart>S</NamePart>
                            <NamePart>Peterson</NamePart>
                        </NamePartList>
                    </Name>
                    <CustomSupplierParameterList>
                        <CustomSupplierParameter>
                            <Name>DateOfBirth</Name>
                            <Value>16/04/1974</Value>
                        </CustomSupplierParameter>
                    </CustomSupplierParameterList>
                </Traveller>
            </TravellerList>
             <ContactDetails>
                 <Name>
                    <Title>Mr</Title>
                    <NamePartList>
                        <NamePart>Andy</NamePart>
                        <NamePart>S</NamePart>
                        <NamePart>Peterson</NamePart>
                    </NamePartList>
                 </Name>
                 <Address>
                     <Company>TravelFusion</Company>
                     <Flat>22A</Flat>
                     <BuildingName>Dean's Court</BuildingName>
                     <BuildingNumber>3</BuildingNumber>
                     <Street>St. Georges Road</Street>
                     <Locality>Clifton</Locality>
                     <City>Bristol</City>
                     <Province>Avon</Province>
                     <Postcode>BS1 5UL</Postcode>
                     <CountryCode>GB</CountryCode>
                 </Address>
                 <HomePhone>
                     <InternationalCode>0044</InternationalCode>
                     <AreaCode>12332</AreaCode>
                     <Number>232223</Number>
                     <Extension>3322</Extension>
                 </HomePhone>
                 <WorkPhone>
                     <InternationalCode>0044</InternationalCode>
                     <AreaCode>12332</AreaCode>
                     <Number>232223</Number>
                     <Extension>3322</Extension>
                 </WorkPhone>
                 <MobilePhone>
                     <InternationalCode>0044</InternationalCode>
                     <AreaCode>12332</AreaCode>
                     <Number>232223</Number>
                     <Extension>3322</Extension>
                 </MobilePhone>
                 <Fax>
                     <InternationalCode>0044</InternationalCode>
                     <AreaCode>12332</AreaCode>
                     <Number>232223</Number>
                     <Extension>3322</Extension>
                 </Fax>
                 <Email>andy@hotmail.com</Email>
            </ContactDetails>
            <BillingDetails>
                <Name>
                    <Title>Mr</Title>
                    <NamePartList>
                        <NamePart>Andy</NamePart>
                        <NamePart>S</NamePart>
                        <NamePart>Peterson</NamePart>
                    </NamePartList>
                </Name>
                <Address>
                     <Company>TravelFusion</Company>
                     <Flat>22A</Flat>
                     <BuildingName>Dean's Court</BuildingName>
                     <BuildingNumber>3</BuildingNumber>
                     <Street>St. Georges Road</Street>
                     <Locality>Clifton</Locality>
                     <City>Bristol</City>
                     <Province>Avon</Province>
                     <Postcode>BS1 5UL</Postcode>
                     <CountryCode>GB</CountryCode>
                </Address>
                <CreditCard>
                     <Company>Travelfusion</Company>
                     <NameOnCard>
                        <NamePartList>
                            <NamePart>Mr Andy S Peterson</NamePart>
                        </NamePartList>
                     </NameOnCard>
                     <Number>5411666677775555</Number>
                     <SecurityCode>887</SecurityCode>
                     <ExpiryDate>01/12</ExpiryDate>
                     <StartDate>01/03</StartDate>
                     <CardType>MasterCard</CardType>
                     <IssueNumber>0</IssueNumber>
                </CreditCard>
            </BillingDetails>
        </BookingProfile>
    </StartTermsHotel>
</CommandList>

The response will contain a TFBookingReference element. This is the Travelfusion booking reference for this booking. Note that the booking is not actually executed until the StartHotelBooking request is submitted.

Response (xml spec detail)

<CommandList>
    <StartTermsHotel millis="271">
        <LoginId>*****</LoginId>
        <RoutingId>Z1292STFA2LK24T5</RoutingId>
        <TFBookingReference>Z1NQS4WTZ</TFBookingReference>
    </StartTermsHotel>
</CommandList>

Step 4: CheckTermsHotel

The CheckTermsHotel request retrieves the result of the previous (StartTermsHotel) request.

Request (xml spec detail)

<CommandList>
    <CheckTermsHotel>
        <XmlLoginId>*****</XmlLoginId>
        <LoginId>*****</LoginId>
        <TFBookingReference>Z1NQS4WTZ</TFBookingReference>
    </CheckTermsHotel>
</CommandList>

The response may contain an updated Router element with required parameters (like whether date of birth is required per traveller, etc.), extra supplier information (terms, credit card requirements, etc.), and possibly a supported payment card list (if supplied at this stage). A Router element is also returned which will contain any new data related to the hotel option / price. The value of Status element indicates the status of the Terms stage.

TermsInProgress - User must re-submit CheckTermsHotel request until the status changes. The delay between resubmissions should be at least 2 seconds.
TermsFailed - User can no longer proceed with booking process
TermsSucceeded - User can proceed in the next stage and continue with booking process

Response (xml spec detail)

<CommandList>
    <CheckTermsHotel millis="36">
        <LoginId>*****</LoginId>
        <TFBookingReference>Z1NQS4WTZ</TFBookingReference>
        <Status>TermsSucceeded</Status>
        <Router>
            <RequiredParameterList>
                <RequiredParameter>
                    <PerRoom>false</ PerRoom>
                    <Name>DateOfBirth</Name>
                    <DisplayText>Date of birth (dd/mm/yyyy)</DisplayText>
                    <PerPassenger>true</PerPassenger>
                    <IsOptional>false</IsOptional>
                </RequiredParameter>
                ...
            </RequiredParameterList>
            ...
            <ResultList>
                ...
            </ResultList>
            <SupplierInfoList>
                <SupplierInfo>
                    <DisplayName>Terms and conditions</DisplayName>
                    <InfoType>url</InfoType>
                    <Info>https://www.hrs.com/web3/showCmsPage.do?clientId=ZW5fX05FWFQ-&amp;cid=3-2&amp;pageId=conditions&amp;noBack=true</Info>
                </SupplierInfo>
                ...
            </SupplierInfoList>
        </Router>
    </CheckTermsHotel>
</CommandList>

Step 5: StartBookingHotel

The StartBookingHotel request is used to initiate the booking. The FakeBooking element is required for development purposes only. If FakeBooking is omitted or set to false, a real booking will be made.

Request (xml spec detail)

<CommandList>
    <StartBookingHotel>
        <XmlLoginId>*****</XmlLoginId>
        <LoginId>*****</LoginId>
        <TFBookingReference>Z1NQS4WTZ</TFBookingReference>
        <FakeBooking>
            <EnableFakeBooking>false</EnableFakeBooking>
            <FakeBookingSimulatedDelaySeconds>0</FakeBookingSimulatedDelaySeconds>
            <FakeBookingStatus>Succeeded</FakeBookingStatus>
        </FakeBooking>
    </StartBookingHotel>
</CommandList>

Response (xml spec detail)

<CommandList>
    <StartBookingHotel millis="56">
        <LoginId>*****</LoginId>
        <TFBookingReference>Z1NQS4WTZ</TFBookingReference>
    </StartBookingHotel>
</CommandList>

Step 6: CheckBookingHotel

The CheckBookingHotel request retrieves the result of the previous (StartBookingHotel) request.

Request (xml spec detail)

<CommandList>
    <CheckBookingHotel>
        <XmlLoginId>*****</XmlLoginId>
        <LoginId>*****</LoginId>
        <TFBookingReference>Z1NQS4WTZ</TFBookingReference>
    </CheckBookingHotel>
</CommandList>

The CheckBookingHotel response contains the latest status of the booking.

Response (xml spec detail)

<CommandList>
    <CheckBookingHotel millis="27">
        <LoginId>*****</LoginId>
        <TFBookingReference>Z1NQS4WTZ</TFBookingReference>
        <Status>Succeeded</Status>
        <SupplierReference>theo-test-ref</SupplierReference>
    </CheckBookingHotel>
</CommandList>



Step 7: StartBookingCancelHotel

Initiates a booking cancellation request. It requires the TF booking reference. Please note - we strongly advise that you check the terms and conditions of the booking you wish to cancel, before cancelling it. You can do that using the GetBookingDetails command (see GetBookingDetails request and response).


Request (xml spec detail)

<CommandList>
    <StartBookingCancelHotel>
        <XmlLoginId>*****</XmlLoginId>
        <LoginId>*****</LoginId>
        <TFBookingReference>Z1NQS4WTZ</TFBookingReference>
    </StartBookingCancelHotel>
</CommandList>


The CheckBookingHotel response contains the latest status of the booking.

Response (xml spec detail)

<CommandList>
    <StartBookingCancelHotel>
        <LoginId> ***** </LoginId>
        <TFBookingReference>Z1NQS4WTZ</TFBookingReference>
    </StartBookingCancelHotel>
</CommandList>


Step 8: CheckBookingCancelHotel

Checks the progress of the cancellation initiated in step 7. Users may repeat this request until the cancellation stage is complete.

Request (xml spec detail)

<CommandList>
    <CheckBookingCancelHotel>
        <XmlLoginId>*****</XmlLoginId>
        <LoginId>*****</LoginId>
        <TFBookingReference>Z1NQS4WTZ</TFBookingReference>
    </CheckBookingCancelHotel>
</CommandList>


The CheckBookingHotel response contains the latest status of the booking.

Response (xml spec detail)

<CommandList>
    <CheckBookingCancelHotel>
        <XmlLoginId>*****</XmlLoginId>
        <TFBookingReference> Z1NQS4WTZ </TFBookingReference>
        <Status>CancelSucceeded</Status>
        <SupplierReference>SUPTESTREF</SupplierReference>
    </CheckBookingCancelHotel>
</CommandList>