This guide is designed to give a quick start to your integration with the Travelfusion 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.

Step 1: Connection

The first step in the integration process is to create a connection to the Travelfusion servers and submit the Login request. This is fully described in the Connection Guide. The purpose of this is to receive your LoginId which you will submit with every XML request in future as authentication and identification. In each XML request there are 2 login fields that must be submitted - the XmlLoginId and the LoginId. You should initially insert your LoginId into both of these fields.

By default your LoginId will not change so you will never need to submit the Login request again. However if you would like to make use of more enhanced security options or you would like more details of the significance of the XmlLoginId and LoginId, please see our Login Handling Guide.

Step 2: Submitting the search request

The StartRouting request tells Travelfusion what you are looking for. Once this is submitted, the Travelfusion servers will evaluate which suppliers (e.g. easyjet, ryanair etc) and which routes (e.g. LHR to MAD) are relevant to your requirements. For each supplier-route, a Router is created which is responsible for connecting to the related supplier. 

Please see the Routing Guide for details and rules related to how you should specify the locations you wish to search and also for information about our city lists, airport lists, and supplier route lists which may be useful if you wish to calculate whether the user's journey can be covered by any of Travelfusion's suppliers, or for various other uses. 

The example below represents a request for a single (one-way) journey. If a return is required, the ReturnDates element should be included after the OutwardDates element. It's structure should be similar to that of OutwardDates. 

There are many features not demonstrated in the example below (for example the ability to resolve place names like 'London', or to request specifically the airports related to a city instead of using a search radius). For full details of all fields shown in the example, and all other XML functions, see the XML Request/Response Specifications. It is recommended that the Type is set to airportgroup (see the Routing guide for more info). 

StartRouting request XML example

<CommandList>

    <StartRouting>

        <XmlLoginId>****</XmlLoginId>

        <LoginId>****</LoginId>

        <Mode>plane</Mode>

        <Origin>

            <Descriptor>LON</Descriptor>

            <Type>airportgroup</Type>

        </Origin>

        <Destination>

            <Descriptor>MAD</Descriptor>

            <Type>airportcode</Type>

            <Radius>1000</Radius>

        </Destination>

        <OutwardDates>

            <DateOfSearch>27/11/2010-10:00</DateOfSearch>

        </OutwardDates>

        <MaxChanges>1</MaxChanges>

        <MaxHops>2</MaxHops>

        <Timeout>40</Timeout>

        <TravellerList>

            <Traveller>

                <Age>30</Age>

            </Traveller>

        </TravellerList>

        <IncrementalResults>true</IncrementalResults>

    </StartRouting>

</CommandList>

The response to the StartRouting request will not contain any flight data. Instead it will just contain a list of all the Routers that have been launched in relation to your search. The example below shows that two Routers have been launched in response to the search request. One of these routers is searching Air Berlin for the route STN to MAD, and the other is searching British Airways from LHR to MAD. Also, a RoutingId is returned that must be submitted in later requests to identify this search. 

StartRouting response XML example

<CommandList>

    <StartRouting>

        <RoutingId>Z1LXGWR0QX1XKAN3</RoutingId>

        <RouterList>

            <Router>

                <Supplier>airberlin</Supplier>

                <Complete>false</Complete>

                <RequestedLocations>

                    <Origin>

                        <Type>airport</Type>

                        <Code>STN</Code>

                    </Origin>

                    <Destination>

                        <Type>airport</Type>

                        <Code>MAD</Code>

                    </Destination>

                </RequestedLocations>

            </Router>

            <Router>

                <Supplier>britishairways</Supplier>

                <Complete>false</Complete>

                <RequestedLocations>

                    <Origin>

                        <Type>airport</Type>

                        <Code>LGW</Code>

                    </Origin>

                    <Destination>

                        <Type>airport</Type>

                        <Code>MAD</Code>

                    </Destination>

                </RequestedLocations>

            </Router>

        </RouterList>

    </StartRouting>

</CommandList>

Step 3: Submitting the results request

The CheckRouting request is used to fetch the latest results in relation to a previous StartRouting request. To do this, only the RoutingId obtained in the previous StartRouting response needs to be submitted as shown in the example below. 

CheckRouting request XML example

<CommandList>

    <CheckRouting>

        <XmlLoginId>****</XmlLoginId>

        <LoginId>****</LoginId>

        <RoutingId>Z1LXGWR0QX1XKAN3</RoutingId>

    </CheckRouting>

</CommandList>

The response will be very similar to the StartRouting response, except that any results received from the related suppliers will now be included within the Router elements as shown in the example below. There will always be the same number of Routerelements as were returned in the StartRouting response. Note that in the example below, the Air Berlin Router still has not received any results from the supplier and so it still has it's Complete status set to false. However the British Airways Routerhas received results and those results are included in a GroupList element. In the case of a return journey, each Group will contain a list of Outward options (as below), and a list of Return options. The round trip journey can only be made of outward and return options that appear within the same group. 

For full details of all fields shown in the example, see the Detailed XML Specification. 

CheckRouting response XML example

<CommandList>

  <CheckRouting>

    <RouterList>

      <Router>

        <Supplier>airberlin</Supplier>

        <Complete>false</Complete>

        <RequestedLocations>

          <Origin>

            <Type>airport</Type>

            <Code>STN</Code>

          </Origin>

          <Destination>

            <Type>airport</Type>

            <Code>MAD</Code>

          </Destination>

        </RequestedLocations>

      </Router>

      <Router>

        <Supplier>britishairways</Supplier>

        <Complete>true</Complete>

        <RequestedLocations>

          <Origin>

            <Type>airport</Type>

            <Code>LGW</Code>

          </Origin>

          <Destination>

            <Type>airport</Type>

            <Code>MAD</Code>

          </Destination>

        </RequestedLocations>

        <GroupList>

          <Group>

            <Id>XR9K06SYQBT4J54B</Id>

            <OutwardList>

              <Outward>

                <Id>N9IPVX2WCO9RV419</Id>

                <CacheInfo>

                  <CacheDataAgeSeconds>0</CacheDataAgeSeconds>

                </CacheInfo>

                <Price>

                  <Amount>45.10</Amount>

                  <Currency>GBP</Currency>

                </Price>

                <Duration>150</Duration>

                <SegmentList>

                  <Segment>

                    <Origin>

                      <Type>airport</Type>

                      <Code>LGW</Code>

                    </Origin>

                    <Destination>

                      <Type>airport</Type>

                      <Code>MAD</Code>

                    </Destination>

                    <DepartDate>27/08/2006-19:20</DepartDate>

                    <ArriveDate>27/08/2006-22:50</ArriveDate>

                    <Duration>150</Duration>

                    <Operator>

                      <Name>British Airways</Name>

                      <Code>BA</Code>

                    </Operator>

                    <VendingOperator>

                      <Name>British Airways</Name>

                      <Code>BA</Code>

                    </VendingOperator>

                    <FlightId>

                      <Code>BA2470</Code>

                      <Number>2470</Number>

                    </FlightId>

                    <TravelClass>

                      <TfClass>Economy With Restrictions</TfClass>

                      <SupplierClass>Traveller</SupplierClass>

                    </TravelClass>

                  </Segment>

                </SegmentList>

                <Vendor>

                  <Name>BritishAirways</Name>

                  <Url>http://www.batraveltrade.com</Url>

                </Vendor>

              </Outward>

              <Outward>

                <Id>NUFSZGQK4HFQJ6YW</Id>

                <CacheInfo>

                  <CacheDataAgeSeconds>0</CacheDataAgeSeconds>

                </CacheInfo>

                <Price>

                  <Amount>60.10</Amount>

                  <Currency>GBP</Currency>

                </Price>

                <Duration>145</Duration>

                <SegmentList>

                  <Segment>

                    <Origin>

                      <Type>airport</Type>

                      <Code>LGW</Code>

                    </Origin>

                    <Destination>

                      <Type>airport</Type>

                      <Code>MAD</Code>

                    </Destination>

                    <DepartDate>27/08/2006-09:00</DepartDate>

                    <ArriveDate>27/08/2006-12:25</ArriveDate>

                    <Duration>145</Duration>

                    <Operator>

                      <Name>British Airways</Name>

                      <Code>BA</Code>

                    </Operator>

                    <VendingOperator>

                      <Name>British Airways</Name>

                      <Code>BA</Code>

                    </VendingOperator>

                    <FlightId>

                      <Code>BA2464</Code>

                      <Number>2464</Number>

                    </FlightId>

                    <TravelClass>

                      <TfClass>Economy With Restrictions</TfClass>

                      <SupplierClass>Traveller</SupplierClass>

                    </TravelClass>

                  </Segment>

                </SegmentList>

                <Vendor>

                  <Name>BritishAirways</Name>

                  <Url>http://www.batraveltrade.com</Url>

                </Vendor>

              </Outward>

              <Outward>

                <Id>7Q042W3X3RCTXFQ3</Id>

                <CacheInfo>

                  <CacheDataAgeSeconds>0</CacheDataAgeSeconds>

                </CacheInfo>

                <Price>

                  <Amount>60.10</Amount>

                  <Currency>GBP</Currency>

                </Price>

                <Duration>145</Duration>

                <SegmentList>

                  <Segment>

                    <Origin>

                      <Type>airport</Type>

                      <Code>LGW</Code>

                    </Origin>

                    <Destination>

                      <Type>airport</Type>

                      <Code>MAD</Code>

                    </Destination>

                    <DepartDate>27/08/2006-14:50</DepartDate>

                    <ArriveDate>27/08/2006-18:15</ArriveDate>

                    <Duration>145</Duration>

                    <Operator>

                      <Name>British Airways</Name>

                      <Code>BA</Code>

                    </Operator>

                    <VendingOperator>

                      <Name>British Airways</Name>

                      <Code>BA</Code>

                    </VendingOperator>

                    <FlightId>

                      <Code>BA2466</Code>

                      <Number>2466</Number>

                    </FlightId>

                    <TravelClass>

                      <TfClass>Economy With Restrictions</TfClass>

                      <SupplierClass>Traveller</SupplierClass>

                    </TravelClass>

                  </Segment>

                </SegmentList>

                <Vendor>

                  <Name>BritishAirways</Name>

                  <Url>http://www.batraveltrade.com</Url>

                </Vendor>

              </Outward>

            </OutwardList>

          </Group>

        </GroupList>

      </Router>

    </RouterList>

  </CheckRouting>

</CommandList>

While there are Routers with Complete set to false, further CheckRouting requests should be submitted with a suitable delay between each (at least 2 seconds). Note that in order to save bandwidth and processing, the contents of the GroupList for a completed Router will only be returned in full detail once. So, for example if the CheckRouting request above is submitted again, the British Airways Router will look like this: 

Example of a complete Router that has already returned it's results in a previous CheckRouting response

<Router>

    <Supplier>britishairways</Supplier>

    <Complete>true</Complete>

    <RequestedLocations>

        <Origin>

            <Type>airport</Type>

            <Code>LGW</Code>

        </Origin>

        <Destination>

            <Type>airport</Type>

            <Code>MAD</Code>

        </Destination>

    </RequestedLocations>

    <GroupList ecode="2-107-2735" etext="All results filtered out" edate="21/05/2006-20:37"/>

</Router>

Note that the CheckRouting response may contain cached data. This means that prices may not be completely up to date. Prices may also be updated at a later stage for a number of other reasons. Please see the guide to Caching and Price Changes. 

Step 4: Selecting a flight for booking

Once the end user has decided which flight they would like to book, a ProcessDetails XML request should be made to begin the booking process. In the example, notice the HandoffParametersOnly element must be set to false and note that the OutwardId corresponds to the id of the first British Airways outward result in the example CheckRouting response in step 3. In the case of a return journey, a ReturnId must also be submitted after the OutwardId which will identify the chosen return flight (which must be in the same Group as the outward selection). 

ProcessDetails request XML example

<CommandList>

<ProcessDetails>

<XmlLoginId>****</XmlLoginId>

<LoginId>****</LoginId>

<RoutingId>Z1LXGWR0QX1XKAN3</RoutingId>

<OutwardId>N9IPVX2WCO9RV419</OutwardId>

<HandoffParametersOnly>false</HandoffParametersOnly>

</ProcessDetails>

</CommandList>

The ProcessDetails response can normally be ignored. However it may contain a Router element which will contain any new data related to the flight / price. This is used to handle special cases where the supplier only supplies certain information after a flight has been submitted. For example, some suppliers may not supply the flight number until a specific flight has been chosen. 

ProcessDetails response XML example

<CommandList>

  <ProcessDetails>

    <RoutingId>Z1S7TYN26095TF69</RoutingId>

  </ProcessDetails>

</CommandList>

Step 5: Submitting the booking details

The ProcessTerms XML request is used to submit the travellers' details and credit card details. See the ProcessTerms request specification in the Detailed Specification for more details of the booking profile. The ProcessTerms request relates to the flight selected in the most recent ProcessDetails request.

ProcessTerms request XML example

<CommandList>

  <ProcessTerms>

    <XmlLoginId>****</XmlLoginId>

    <LoginId>****</LoginId>

    <RoutingId>Z1LXGWR0QX1XKAN3</RoutingId>

    <BookingProfile>

      <TravellerList>

        <Traveller>

          <Age>30</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></Company>

           <Flat>22A</Flat>

           <BuildingName>Dean's Court</BuildingName>

           <BuildingNumber>3</BuildingNumber>

           <Street>St. George Street</Street>

           <Locality>Redland</Locality>

           <City>Bristol</City>

           <Province>Avon</Province>

           <Postcode>BS8 6GC</Postcode>

           <CountryCode>GB</CountryCode>

         </Address>

         <HomePhone>

           <InternationalCode>0044</InternationalCode>

           <AreaCode>12332</AreaCode>

           <Number>232223</Number>

           <Extension>3322</Extension>

         </HomePhone>

         <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></Company>

           <Flat>22A</Flat>

           <BuildingName>Dean's Court</BuildingName>

           <BuildingNumber>3</BuildingNumber>

           <Street>St. George Street</Street>

           <Locality>Redland</Locality>

           <City>Bristol</City>

           <Province>Avon</Province>

           <Postcode>BS8 6GC</Postcode>

           <CountryCode>GB</CountryCode>

        </Address>

        <CreditCard>

           <Company></Company>

           <NameOnCard>

            <NamePartList>

              <NamePart>Mr Andy S Peterson</NamePart>

            </NamePartList>

           </NameOnCard>

           <Number>5411666677775555</Number>

           <SecurityCode>887</SecurityCode>

           <ExpiryDate>01/07</ExpiryDate>

           <StartDate>01/03</StartDate>

           <CardType>MasterCard</CardType>

           <IssueNumber>0</IssueNumber>

        </CreditCard>

      </BillingDetails>

    </BookingProfile>

  </ProcessTerms>

</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 StartBooking request is submitted). A Router is also returned which will contain any new data related to the flight / price. THE PROCESSTERMS RESPONSE IS THE ONLY RESPONSE THAT CONTAINS THE EXACT PRICE THAT WILL BE FINALLY CHARGED TO THE CUSTOMER. THEREFORE YOU MUST MAKE SURE THAT THE FINAL PRICE YOU DISPLAY TO THE USER IS CALCULATED BASED ON THIS PRICE, AND NOT THOSE RETURNED AT PREVIOUS STAGES. 

For example in the XML below, a 'Credit card surcharge' is returned which was not known until this stage since it depends upon the card type. Note that the XML below is for an easyjet flight and is not related to the previous examples. See the Detailed XML Specification for more details of the Processterms request / response and the handling of bookings in general. 

ProcessTerms response XML example

<CommandList>

  <ProcessTerms>

    <RoutingId>B1MGUR1D506SYHWL</RoutingId>

    <TFBookingReference>B1KL3B76P</TFBookingReference>

    <Router>

      <Supplier>easyjet</Supplier>

      <Complete>true</Complete>

      <RequestedLocations>

        <Origin>

          <Type>airport</Type>

          <Code>LGW</Code>

        </Origin>

        <Destination>

          <Type>airport</Type>

          <Code>MAD</Code>

        </Destination>

      </RequestedLocations>

      <GroupList>

        <Group>

          <Id>3NCVJ6W86SOMWXRK</Id>

          <OutwardList>

            <Outward>

              <Id>AGG6M1JGCAZEXY0F</Id>

              <CacheInfo>

                <CacheDataAgeSeconds>0</CacheDataAgeSeconds>

              </CacheInfo>

              <Duration>155</Duration>

              <SegmentList>

                <Segment>

                  <Origin>

                    <Type>airport</Type>

                    <Code>LGW</Code>

                  </Origin>

                  <Destination>

                    <Type>airport</Type>

                    <Code>MAD</Code>

                  </Destination>

                  <DepartDate>26/06/2006-07:40</DepartDate>

                  <ArriveDate>26/06/2006-11:15</ArriveDate>

                  <Duration>155</Duration>

                  <Operator>

                    <Name>easyjet</Name>

                    <Code>U2</Code>

                  </Operator>

                  <VendingOperator>

                    <Name>easyjet</Name>

                    <Code>U2</Code>

                  </VendingOperator>

                  <FlightId>

                    <Code>5475</Code>

                    <Number>5475</Number>

                  </FlightId>

                  <TravelClass>

                    <TfClass>Economy With Restrictions</TfClass>

                    <SupplierClass>Economy With Restrictions</SupplierClass>

                  </TravelClass>

                  <SegmentMayEndWithAStop>false</SegmentMayEndWithAStop>

                </Segment>

              </SegmentList>

              <Vendor>

                <Name>EasyJet</Name>

                <Url>http://www.easyjet.com/</Url>

              </Vendor>

            </Outward>

          </OutwardList>

          <Price>

            <Amount>61.44</Amount>

            <Currency>GBP</Currency>

            <PriceIncludesTax>true</PriceIncludesTax>

            <TaxIsEstimated>false</TaxIsEstimated>

            <TaxItemList>

              <TaxItem>

                <Name>Credit card surcharge</Name>

                <Amount>4.95</Amount>

                <Currency>GBP</Currency>

              </TaxItem>

            </TaxItemList>

          </Price>

        </Group>

      </GroupList>

      <SupplierInfoList>

        <SupplierInfo>

          <DisplayName>Terms and Conditions</DisplayName>

          <InfoType>url</InfoType>

          <Info>http://www.easyjet.com/en/book/conditions.php</Info>

        </SupplierInfo>

      </SupplierInfoList>

    </Router>

  </ProcessTerms>

</CommandList>

Step 6: Starting the booking

The StartBooking XML request is used to execute the booking. The TFBookingReference should have the value returned in the previous ProcessTerms response. The ExpectedPrice element must be submitted so that Travelfusion can check that you have displayed the correct price to your user - see the StartBooking request/response spec for more details. The FakeBooking element is used for development purposes to request a simulated booking. If the FakeBooking element is omitted, a real booking will be made. See the Guidelines for more details of fake bookings and booking handling in general. 

StartBooking request XML example

<CommandList>

  <StartBooking>

    <XmlLoginId>****</XmlLoginId>

    <LoginId>****</LoginId>

    <TFBookingReference>B1KL3B76P</TFBookingReference>

    <ExpectedPrice>

        <Amount>22.00</Amount>

  <Currency>GBP</Currency>

    </ExpectedPrice>

    <FakeBooking>

      <EnableFakeBooking>true</EnableFakeBooking>

      <FakeBookingSimulatedDelaySeconds>15</FakeBookingSimulatedDelaySeconds>

      <FakeBookingStatus>Succeeded</FakeBookingStatus>

      <EnableFakeCardVerification>true</EnableFakeCardVerification>

    </FakeBooking>

  </StartBooking>

</CommandList>

The StartBooking request is asynchronous, so a response will be returned immediately (whilst the booking is still in progress in the 'background'). The response will contain no useful information. The CheckBooking request, described below in step 7, is used to retrieve the final status of the booking.  

StartBooking response XML example

<CommandList>

<StartBooking>

<TFBookingReference>B1KL3B76P</TFBookingReference>

</StartBooking>

</CommandList>

Step 7: Retrieving the booking status

The CheckBooking XML request is used to get the latest status of the booking. The TFBookingReference should have the value returned in the previous ProcessTerms response. 

CheckBooking request XML example

<CommandList>

  <CheckBooking>

    <XmlLoginId>****</XmlLoginId>

    <LoginId>****</LoginId>

    <TFBookingReference>B1KL3B76P</TFBookingReference>

  </CheckBooking>

</CommandList>

The CheckBooking response returns the latest status of the booking. While Travelfusion is waiting for a response from the supplier, the status will be BookingInProgress. In this case the CheckBooking request should be resubmitted after a few seconds delay. 

CheckBooking response XML example while booking is still in progress

<CommandList>

  <CheckBooking>

    <TFBookingReference>B1KL3B76P</TFBookingReference>

    <Status>BookingInProgress</Status>

  </CheckBooking>

</CommandList>

In some cases, the supplier may require special verification of the credit card. This involves forwarding the customer to a URL operated by the card issuer (Visa / Mastercard etc). The user then enters a password on the card issuer's website and is returned to a specified URL. The mechanics of this process are explained in detail in the Credit Card Verification Handling Guide.

Once the booking has been completed, the CheckBooking response will contain a different status. For a successful booking the status will be Succeeded and the supplier's booking reference will be returned. A failed booking will have status Failed. There are also situations where the booking has completed but the status is uncertain. For more details of how to handle these cases and bookings in general, please see the Guidelines, with particular reference to the Booking handling guide. 

CheckBooking response XML example once booking is complete

<CommandList>

  <CheckBooking>

    <TFBookingReference>B1KL3B76P</TFBookingReference>

    <Status>Succeeded</Status>

    <SupplierReference>39EGIZ2P5F</TFBookingReference>

  </CheckBooking>

</CommandList>

Step 8: Cancelling a flight booking

A previous booking can be cancelled via the API. This is only available for certain suppliers and bookings. Please contact Travelfusion for more information. The guide can be found here, and the details XML specification can be found here in the 'Air Cancellation' section.