TF Online Checkin API Specification


Introduction

With the Travelfusion Online Checkin API, customers are able to check in travellers on any booking, regardless of whether it was made through Travelfusion, or even through the agent themselves. It applies to any flight in the entire world inventory. This guide is designed to give a quick-start to the users' integration with the TF Online Checkin API.

Summary of functionality

The supported functionality is summarised as follows.

- Interrogate the API for airline online check-in support, advance availability and parameter requirements.
- Initiate a check-in process for a booking by passing in a number of required parameters.
- Update check-in parameters and / or traveller details.
- Retrieve check-in status of the travellers and flight details.
- De-queue an existing check-in request.
- Retrieve the boarding passes for a particular check-in.

In addition to the above functionality, TF offers API users the option to integrate online check-in within their standard TF Search and Book API integration. This option applies only to customers where TF is their one and only flight booking channel. Please contact Travelfusion for more information.

General information and user guidelines

The basic online check-in API interaction flow requires two compulsory steps. Firstly, to request check-in availability as early as possible in the user's booking flow. And lastly, to send the main check-in request at the time of sale of the booking (e.g. at the end of the user's booking flow); this is important, as it is how the API knows the time and the fact that a check-in was sold by the user. For any other than the described usage that the API user may require, please contact Travelfusion.

For example, an end user searches for a flight and selects a result. Next to their selection, or the next step (flight details display), they are shown the option and cost to purchase automatic online check-in. If end user picks the option, the API user must send the availability request to confirm check-in availability. Then, when the end user successfully completes the booking, the API user must send the check-in request, immediately after receipt of successful booking response.

The API assumes a single check-in request relates to a flight booking with a unique PNR. A single TF check-in reference is generated which uniquely identifies the TF online check-in for that booking. The API automatically checks in all travellers requested for that booking (for all its legs / segments and directions). However, the check-in status of a TF online check-in is reported per traveller per flight direction (outbound / inbound).

The API constantly monitors airlines for changes in the check-in opening times / availability and changes or cancellations of the checked-in flights. If a flight cancellation is a result of the API user's action, then the API user is responsible for issuing a de-queue request. The up-to-date flight details will be shown in every check-in flight details response.

The basic error code and handling is similar to this in Search and Book API which is described in the Error Codes and Handling Guide. Any deviation from the general error handling guide will be described in the XML commands section.

XML commands

This section contains a more detailed explanation of the API XML commands, including XML examples.

CheckinAvailabilityPlane Request

Initiates a check for online check-in availability. It requires a TF airline code and the airport route. A list of TF airline codes may be obtained by using the GetAirlinesData XML command.

<CommandList>
  <CheckinAvailabilityPlane>
    <XmlLoginId>***</XmlLoginId>
    <LoginId>***</LoginId>
    <Airline>
      <TFCode>FR</TFCode>
    </Airline>
    <Criteria>
      <AirportcodeRoute>LHR-MAD</AirportcodeRoute>
      <TravellerList>
        <Traveller>
          <Age>30</Age>
          <IdCountryOfIssue>FR</IdCountryOfIssue>  // The country code (ISO 3166 alpha-2)
        </Traveller>
      </TravellerList>
    </Criteria>
  </CheckinAvailabilityPlane>
</CommandList>

The <AirportcodeRoute> should contain two IATA codes for a single flight, three codes for a return flight (also, open-jaw example: LHR-MAD-LGW). Users should explicitly specify the ages of the travellers. If ages are not known, it is recommended to use 30 for adults, 9 for children and 1 for infants.

CheckinAvailabilityPlane Response

The response contains <IsAvailable> element. If check-in is available, the response includes all advance availability, authentication and check-in parameters that would be required if the user wanted to initiate the actual check-in process.

<CommandList>
  <CheckinAvailabilityPlane>
    <LoginId>***</LoginId>
    <Airline>
      <TFCode>FR</TFCode>
    </Airline>
    <IsAvailable>true</IsAvailable>
    <AdvanceAvailabilityList>
      <AdvanceAvailability>
        <Category>default</Category>  // default, seat_selected
        <Direction>outbound</Direction>  // outbound, inbound, both
        <TimeUnit>MINUTES</TimeUnit>
        <From>10080</From>
        <To>120</To>
      </AdvanceAvailability>
      <AdvanceAvailability>
        <Category>seat_purchased</Category>
        <Direction>outbound</Direction>
        <TimeUnit>MINUTES</TimeUnit>
        <From>43200</From>
        <To>120</To>
      </AdvanceAvailability>
    </AdvanceAvailabilityList>
    <AdvanceAvailability>5d8h30m</AdvanceAvailability>
    <AuthOptionList>
      <AuthOption>
        <AuthOptionItemList>
          <AuthOptionItem>
            <Name>CC_LAST_4_DIGIT</Name>
            <DisplayText>Last 4 digits of Credit/Debit Number</DisplayText>
          </AuthOptionItem>
          <AuthOptionItem>
            <Name>BOOKING_REFERENCE</Name>
            <DisplayText>Booking reference or reservation number</DisplayText>
          </AuthOptionItem>
        </AuthOptionItemList>
      </AuthOption>
    </AuthOptionList>
    <ParameterOptionList>
      <ParameterOption>
        <ParameterOptionItemList>
          <ParameterOptionItem>
            <Name>PASSENGER_DATE_OF_BIRTH</Name>
            <DisplayText>Date of birth (dd/mm/yyyy)</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>PASSENGER_COUNTRY_OF_ORIGIN</Name>
            <DisplayText>Country of birth (two-letter code, e.g. GB)</DisplayText>
          </ParameterOptionItem>
        </ParameterOptionItemList>
      </ParameterOption>
    </ParameterOptionList>
  </CheckinAvailabilityPlane>
</CommandList>

Airlines may have different advance availability times depending on various factors (e.g. outbound vs inbound flight, or whether customer has already selected a seat or not, etc.) These are described in the <AdvanceAvailabilityList> element, as per the above XML example.

The <ParameterOptionItemList> describes all possible check-in options. See further below for examples.
The <DisplayText> is designed to be passed directly to the end user, so that if any new types of data are required it will work automatically without the need for development on the API-customer side.
However if you do not wish to use TF's suggested display text, you should predefine your own text and ensure that when unrecognised fields are received, you detect this and build support for it as soon as possible.
Alternatively, you could request that TF return a specific DisplayText and we can configure it on our side.

CheckinPlane Request

Instructs the API to queue an automated online check-in with the given parameters, as shown in the XML example below. This request must be sent at booking sale time.

The user may re-submit this request at a later time, if they need to update check-in parameters. In this case, the <TFCheckinReference> of an existing check-in must be included. The <UserParameterList> and <AuthOption> are updated as one piece, so they always need to be complete. Whereas the <TravellerList> would update in an incremental or override way.

The <UserParameterList> contains a number of parameters the user of the API may input in order to customise various functionality of the check-in. It should include the email where the boarding pass(es) will be emailed to (NOTE: the airline may not support an email address for checkin and may use the email address submitted at booking time). Other parameters like locale, phone numbers, email bcc, etc. may be user. Please contact Travelfusion, if any additional parameters are required.

The <AuthOption> is mandatory; if it is not present, then the response will contain an <AuthOptionList> same as in the CheckinAvailabilityPlane response. Users must pick one of the options in the <AuthOptionList> and use it in this request.

The <TravellerList> is mandatory; if it is not present, then the response will contain an <ParameterOptionList> same as in the CheckinAvailabilityPlane response. Users must pick at least one of the options in the <ParameterOptionList> and use it inside every <Traveller> element.

A <ParameterOption> (per traveller) contains all the check-in parameters required. In case of a return flight, and if the traveller or agent requires to check in with different parameters (that are supported) per flight direction, then two <ParameterOption> elements must be specified; one with 'outbound' and another with 'inbound' values for <Direction>. In case of a single flight, the <Direction> can be omitted, or if present, it should have value of 'both'.

If the booking was made via Travelfusion, then it is recommended users include the <TFBookingReference> if available.

<CommandList>
  <CheckinPlane>
    <XmlLoginId>***</XmlLoginId>
    <LoginId>***</LoginId>
    <TFBookingReference>R12XC004H</TFBookingReference>
    <TFCheckinReference>R12XC004H</TFCheckinReference>
    <UserParameterList>
      <UserParameter>
        <Name>emailto</Name>
        <Value>jimsmith@email.com</Value>
      </UserParameter>
      <UserParameter>
        <Name>emailbcc</Name>
        <Value>apiuser@email.com</Value>
      </UserParameter>
      <UserParameter>
        <Name>locale</Name>
        <!-- 'ISO 639 alpha-2 language code'_'ISO 3166 alpha-2 country code' -->
        <Value>it_CH</Value>
      </UserParameter>
      <UserParameter>
        <Name>brand</Name>
        <Value>FLYWITHUS</Value>
      </UserParameter>
      <UserParameter>
        <Name>phone</Name>
        <Value>02248344174</Value>
      </UserParameter>
    </UserParameterList>
    <Airline>
      <TFCode>FR</TFCode>
    </Airline>
    <AuthOption>
      <AuthOptionItemList>
        <AuthOptionItem>
          <Name>TRAVELLER_SURNAME</Name>
          <Value>Smith</Value>
        </AuthOptionItem>
        <AuthOptionItem>
          <Name>BOOKING_REFERENCE</Name>
          <Value>ABCDEF</Value>
        </AuthOptionItem>
      </AuthOptionItemList>
    </AuthOption>
    <TravellerList>
      <Traveller>
        <Name>
          <Title>Mr</Title>
          <NamePartList>
            <NamePart>Andy</NamePart>
            <NamePart>S</NamePart>
            <NamePart>Smith</NamePart>
          </NamePartList>
        </Name>
        <ParameterOption>
          <Direction>outbound</Direction>
          <ParameterOptionItemList>
            <ParameterOptionItem>
              <Name>PASSPORT_NUMBER</Name>
              <Value>11111</Value>
            </ParameterOptionItem>
            <ParameterOptionItem>
              <Name>PASSENGER_DATE_OF_BIRTH</Name>
              <Value>21/04/1970</Value>
            </ParameterOptionItem>
          </ParameterOptionItemList>
        </ParameterOption>
      </Traveller>
    </TravellerList>
  </CheckinPlane>
</CommandList>

CheckinPlane Response

It contains a <TFCheckinReference> that identifies this check-in request.

<CommandList>
  <CheckCheckinPlane>
    <LoginId>***</LoginId>
    <TFCheckinReference>R12XC004H</TFCheckinReference>
  </CheckCheckinPlane>
</CommandList>

GetCheckinDetailsPlane Request

Use this to check the current status of a check-in and flight details, given the <TFCheckinReference>.

<CommandList>
  <GetCheckinDetailsPlane>
    <XmlLoginId>***</XmlLoginId>
    <LoginId>***</LoginId>
    <TFCheckinReference>R12XC004H</TFCheckinReference>
  </GetCheckinDetailsPlane>
</CommandList>

GetCheckinDetailsPlane Response

The response contains the status of the check-in per traveller per flight direction. It also contains the flight details. The <OutboundStatus> and <InboundStatus> elements contain one of the following values:

IN_PROGRESS - The check-in has been initiated. In case of return flights, the <InboundStatus> will remain in this status until inbound check-in has opened.

ERROR - There was an error that prevented the check-in. This would be an error that needs to be dealt with by the API user. A notification email is sent to the recipients specified in the user parameters of the check-in request. The status will contain attributes ecode, etext, edetail and edate that explain the problem, e.g. a traveller was missing from the list or had a wrong name.

COMPLETE - Traveller is successfully checked in.

UNCONFIRMED - The check-in may or may not have been made. User should contact Travelfusion for resolution.

DE-QUEUED - The check-in was requested by the API user to be de-queued.

ABORT_FAILED - This is assigned to check-ins that are still in an non-final status few hours before flight time. An notification email would be sent to the recipients specified in the user parameters of the check-in request.

<CommandList>
  <GetCheckinDetailsPlane>
    <LoginId>***</LoginId>
    <TFCheckinReference>R12XC004H</TFCheckinReference>
    <Airline>
      <TFCode>FR</TFCode>
    </Airline>
    <TravellerList>
      <Traveller>
        <Name>
          <Title>Mr</Title>
          <NamePartList>
            <NamePart>Andy</NamePart>
            <NamePart>S</NamePart>
            <NamePart>Peterson</NamePart>
          </NamePartList>
        </Name>
        <CheckedIn>
          <OutboundStatus>IN_PROGRESS</OutboundStatus>
          <InboundStatus>IN_PROGRESS</InboundStatus>
        </CheckedIn>
      </Traveller>
    </TravellerList>
    <FlightDetailsAuditList>
      <FlightDetailsAudit>
        <Timestamp>03/02/2016-14:43</Timestamp>
        <FlightDetails>
          <SegmentOutList>
            <SegmentOut>FR 1234|LTN|MAD|10/12/2016-14:45|10/11/2016-14:45|LTNDEP_1</SegmentOut>
            <SegmentOut>FR 5678|MAD|BUD|10/12/2016-19:15|10/11/2016-14:45|Terminal 2B</SegmentOut>
          </SegmentOutList>
          <SegmentRetList>
            <SegmentRet>FR 4321|BUD|MAD|17/12/2016-13:45|17/11/2016-13:45|Terminal 1A</SegmentRet>
            <SegmentRet>FR 8765|MAD|LTN|17/12/2016-19:15|17/11/2016-13:45|MAD-T4</SegmentRet>
          </SegmentRetList>
        </FlightDetails>
      </FlightDetailsAudit>
    </FlightDetailsAuditList>
  </GetCheckinDetailsPlane>
</CommandList>

CheckinDequeuePlane Request

Instructs the API to de-queue a check-in that was previously requested via the CheckinPlane command. The de-queueing can be successfully performed up until few hours before the flight time.

<CommandList>
  <CheckinDequeuePlane>
    <XmlLoginId>***</XmlLoginId>
    <LoginId>***</LoginId>
    <TFCheckinReference>R12XC004H</TFCheckinReference>
  </CheckinDequeuePlane>
</CommandList>

CheckinDequeuePlane Response

The response contains <TravellerList> element with check-in status per traveller at the time of de-queueing.

<CommandList>
  <CheckinDequeuePlane>
    <LoginId>***</LoginId>
    <Airline>
      <TFCode>FR</TFCode>
    </Airline>
    <TravellerList>
      <Traveller>
        <Name>
          <Title>Mr</Title>
          <NamePartList>
            <NamePart>Andy</NamePart>
            <NamePart>S</NamePart>
            <NamePart>Peterson</NamePart>
          </NamePartList>
        </Name>
       <CheckedIn>
          <OutboundStatus>IN_PROGRESS<OutboundStatus>
          <InboundStatus>IN_PROGRESS<InboundStatus>
        </CheckedIn>
      </Traveller>
    </TravellerList>
  </CheckinDequeuePlane>
</CommandList>

GetCheckinBoardingPass Request

This request is used to download the current boarding passes. If <Method> is 'email', then this will only result in re-sending the confirmation emails; the response will not contain any boarding pass data. If <Method> is 'inline', the response will contain the hex-encoded data of all boarding passes for the given check-in reference. This request should be the result of an end user action, and it is not supposed to be used automatically for every single check-in.

<CommandList>
  <GetCheckinBoardingPass>
    <XmlLoginId>***</XmlLoginId>
    <LoginId>***</LoginId>
    <TFCheckinReference>R12XC004H</TFCheckinReference>
    <Method>inline</Method>
  </GetCheckinBoardingPass>
</CommandList>

GetCheckinBoardingPass Response

The response contains a list of boarding pass attachments.

<CommandList>
  <GetCheckinBoardingPass>
    <LoginId>***</LoginId>
    <TFCheckinReference>R12XC004H</TFCheckinReference>
    <BoardingPassList>
      <BoardingPass>
        <Type>application/pdf</Type> // MIME type, e.g. text/html, image/jpg, etc.
        <Data>...<Data>
      </BoardingPass>
      <BoardingPass>
        ...
      </BoardingPass>
      ...
    </BoardingPassList>
  </GetCheckinBoardingPass>
</CommandList>

Test Online Check-in using <FakeCheckin>

The fake-check-in test allows users to test the TF Online Checkin API without having to connect to the airlines.

Simple FakeCheckin example

Request

<CommandList>
  <CheckinPlane>
    <XmlLoginId>***</XmlLoginId>
    <LoginId>***</LoginId>
    <FakeCheckin>
      <EnableFakeCheckin>true</EnableFakeCheckin>
    </FakeCheckin>
    <UserParameterList>
       <UserParameter>
          <Name>emailto</Name>
          <Value>name@email.com</Value>
       </UserParameter>
    </UserParameterList>
    <Airline>
      <TFCode>U2</TFCode>
    </Airline>
    <Test>true</Test>
    <AuthOption>
      <AuthOptionItemList>
        <AuthOptionItem>
          <Name>TRAVELLER_SURNAME</Name>
          <Value>Smith</Value>
        </AuthOptionItem>
        <AuthOptionItem>
          <Name>BOOKING_REFERENCE</Name>
          <Value>EQ566MN</Value>
        </AuthOptionItem>
      </AuthOptionItemList>
    </AuthOption>
  </CheckinPlane>
</CommandList>

Response

The response will result in a successful complete check-in, using random (but airline valid) data for the flight / check-in times and traveller information.

Enhanced FakeCheckin example

This example shows how a user can change the parameters of the test fake-check-in. The required error codes (if needed) can be found in the response of the GetErrorCodes API specification.

Request

<CommandList>
  <CheckinPlane>
    <XmlLoginId>***</XmlLoginId>
    <LoginId>***</LoginId>

    <!-- OPTIONAL - If present, the flight data will be taken from this TF booking. The booking itself could be either real or fake -->
    <TFBookingReference>Z1HFZB2NW</TFBookingReference>

    <FakeCheckin>
      <EnableFakeCheckin>true</EnableFakeCheckin>

      <!-- OPTIONAL - If present here, it should not be present in the <TravellerList> -->
      <FakeCheckinStatusList>
        <FakeCheckinStatus>
          <!-- OPTIONAL - If missing, the status applies to both directions -->
          <Direction>outbound</Direction>
          <Status>COMPLETE</Status>
        </FakeCheckinStatus>
        <FakeCheckinStatus>
          <Direction>inbound</Direction>
          <Status>ERROR</Status>
          <ErrorCode>
            <!-- If missing, it uses a random valid error code -->
            <Code>34-17000</Code>
          </ErrorCode>
        </FakeCheckinStatus>
      </FakeCheckinStatusList>

      <!-- OPTIONAL - If missing, a random arline valid route is picked (always return) -->
      <AirportcodeRoute>LHR-MAD-LHR</AirportcodeRoute>

      <!-- OPTIONAL - If missing, a random valid outbound time is picked -->
      <FlightTimeOutbound>16/02/16-10:00</FlightTimeOutbound>
      <!-- OPTIONAL - If missing, a random valid inbound time is picked (if return flight; ignored if single) -->
      <FlightTimeInbound>19/02/16-10:00</FlightTimeInbound>

      <!-- OPTIONAL - Overrides advance availability. If missing, it picks it up from the airline -->
      <AdvanceAvailabilityList>
        <AdvanceAvailability>
          <Direction>outbound</Direction>
          <TimeUnit>MINUTES</TimeUnit>
          <From>43200</From>
          <To>120</To>
        </AdvanceAvailability>
        <AdvanceAvailability>
          <Direction>inbound</Direction>
          <TimeUnit>MINUTES</TimeUnit>
          <From>43200</From>
          <To>120</To>
        </AdvanceAvailability>
      </AdvanceAvailabilityList>
    </FakeCheckin>

    <UserParameterList>
      <UserParameter>
        <Name>emailto</Name>
        <Value>name@email.com</Value>
      </UserParameter>
    </UserParameterList>
    <Airline>
      <TFCode>U2</TFCode>
    </Airline>
    <Test>true</Test>
    <AuthOption>
      <AuthOptionItemList>
        <AuthOptionItem>
          <Name>TRAVELLER_SURNAME</Name>
          <Value>Smith</Value>
        </AuthOptionItem>
        <AuthOptionItem>
          <Name>BOOKING_REFERENCE</Name>
          <Value>EQ566MN</Value>
        </AuthOptionItem>
      </AuthOptionItemList>
    </AuthOption>
    <TravellerList>
      <Traveller>
        <Name>
          <Title>Mr</Title>
          <NamePartList>
            <NamePart>Andy</NamePart>
            <NamePart>S</NamePart>
            <NamePart>Smith</NamePart>
          </NamePartList>
        </Name>
        <ParameterOption>
          <ParameterOptionItemList>
            <ParameterOptionItem>
              <Name>PASSPORT_NUMBER</Name>
              <Value>11111</Value>
            </ParameterOptionItem>
            <ParameterOptionItem>
              <Name>PAX_DATE_OF_BIRTH</Name>
              <Value>21/04/1970</Value>
            </ParameterOptionItem>
          </ParameterOptionItemList>
        </ParameterOption>

        <!-- OPTIONAL - Can go inside any <Traveller> as required. If present here, it should not be present inside <FakeCheckin> -->
        <FakeCheckinStatusList>
          <FakeCheckinStatus>
            <Direction>outbound</Direction>
            <Status>COMPLETE</Status>
          </FakeCheckinStatus>
          <FakeCheckinStatus>
            <Direction>inbound</Direction>
            <Status>ERROR</Status>
            <ErrorCode>
              <Code>34-17000</Code>
            </ErrorCode>
          </FakeCheckinStatus>
        </FakeCheckinStatusList>

      </Traveller>
    </TravellerList>
  </CheckinPlane>
</CommandList>





Comments