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

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.
  CheckDetailsHotel
 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.
  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.  CheckBookingHotel, contains the status of the booking stage.

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>
        <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.), and possibly a supported payment card list (if supplied at this stage).

Response (xml spec detail)

<CommandList>
    <CheckDetailsHotel millis="0">
        <LoginId>*****</LoginId>
        <RoutingId>*****</RoutingId>
        <Router>
            <RequiredParameterList>
                <RequiredParameter>
                    <Name>DateOfBirth</Name>
                    <DisplayText>Date of birth (dd/mm/yyyy)</DisplayText>
                    <PerPassenger>true</PerPassenger>
                    <IsOptional>false</IsOptional>
                </RequiredParameter>
                <RequiredParameter>
                    <Name>DateOfBirthIsNotRequiredForAdults</Name>
                    <DisplayText></DisplayText>
                    <PerPassenger>true</PerPassenger>
                    <IsOptional>true</IsOptional>
                </RequiredParameter>
                <RequiredParameter>
                    <Name>GuestNameRequiredPerBooking</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 this status changes
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>
                    <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>