TF Online Checkin API Specification

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.

The supported functionality is summarised as follows:

Users may interrogate the API to find out whether an airline supports online check-in for a particular booking or not.
Then users may instruct the API to initiate the check-in process by passing in a number of required parameters.
Users may update an existing checkin request with additional parameters.
Finally, users may request, at a later time, details and status of the travellers' check-in for a flight.

The following is a detailed explanation of the API XML commands, including XML examples.

CheckinAvailabilityPlane REQUEST (xml spec detail)

Initiates a check for online check-in availability. The purpose of CheckinAvailabilityPlane is to inform

a) whether automated online check-in is offered or not,
b) provide check-in opening time window (before flight), and
c) list all required parameters needed for the CheckinPlane request.

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 (online check-in available) (xml spec detail)

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>PAX_DATE_OF_BIRTH</Name>
            <DisplayText>Date of birth of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>PAX_COUNTRY_OF_ORIGIN</Name>
            <DisplayText>Country of origin of the trallever</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.


CheckinAvailabilityPlane RESPONSE (online check-in not available) (xml spec detail)

If online check-in is not supported by the airline, then the element <IsAvailable> will contain value false.

<CommandList>
  <CheckinAvailabilityPlane>
    <LoginId>***</LoginId>
    <Airline>
      <TFCode>FR</TFCode>
    </Airline>
    <IsAvailable ecode="2-2444" etext="Invalid airportcode route" edetail="LHR-MAD-LGW" edate="31/03/2015-07:34">false</IsAvailable>
  </CheckinAvailabilityPlane>
</CommandList>

If check-in is supported, but not for the given criteria (e.g. invalid route or number of infants, etc.), then <IsAvailable> will contain the reason for failure as shown above.

------------------------------------------------------------------------

CheckinPlane REQUEST (xml spec detail)

This request initiates an automated check-in process, or it updates an existing check-in request. The initial check-in request should be submitted when the end user purchases the check-in; this would usually be after flight booking sale time.

A follow up check-in request (that includes the initial check-in reference) could be made in order to add or update the check-in parameters of the initial request; for example, the end user may have purchased the check-in at booking time (it is when initial check-in request is submitted) but they didn't have the passport number with them, then they came back few days ago with their passport number (time when the update check-in request is submitted). Follow-up (or update) requests may be submitted until the check-in opening time comes.

This request is typically submitted before the actual check-in opens. The API is responsible for performing the actual check-in which may happen long in future (long after CheckinPlane request was submitted). It is recommended submitting the CheckinAvailabilityPlane request right before CheckinPlane, as a last moment confirmation the automated online check-in is available indeed. Also, after CheckinPlane response is successfully received with a reference, it is recommended the API user checks the status of the check-in (by using GetCheckinDetailsPlane request).

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>PAX_DATE_OF_BIRTH</Name>
              <Value>21/04/1970</Value>
            </ParameterOptionItem>
          </ParameterOptionItemList>
        </ParameterOption>
      </Traveller>
    </TravellerList>
  </CheckinPlane>
</CommandList>

CheckinPlane RESPONSE (xml spec detail)

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

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

------------------------------------------------------------------------

CheckinDequeuePlane REQUEST

Instructs the API to de-queue a check-in that was previously requested via the CheckinPlane command.

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

------------------------------------------------------------------------

GetCheckinDetailsPlane REQUEST

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

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

GetCheckinDetailsPlane RESPONSE

The <OutboundStatus> and <InboundStatus> elements contain one of the following values: IN_PROGRESS, ERROR, COMPLETE, UNCONFIRMED. Their meaning is explained below.

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. 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.

<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>
  </GetCheckinDetailsPlane>
</CommandList>

------------------------------------------------------------------------


If <IdCountryOfIssue> is not present, the <ParameterOptionItemList> describes all possible check-in options (for all supported ages and nationalities by the airline). If <IdCountryOfIssue> is specified in the criteria, then the <ParameterOptionItemList> will be specific to that (and shorter).
   
    <ParameterOptionList>

      <!-- Option where traveller of any age has (and can check in with) passport issued by EU, EU Schengen, or Andora -->

      <ParameterOption>
        <ParameterOptionItemList>
          <ParameterOptionItem>
            <Name>ID_PASSPORT_NUMBER</Name>
            <!-- 'checkin' parameters are required by the airline to check in -->
            <ParamType>checkin</ParamType>
            <DisplayText>Passport number of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>ID_PASSPORT_COUNTRY_OF_ISSUE</Name>
            <ParamType>checkin</ParamType>
            <!-- Presence of this element indicates a restriction. A list of comma separated country codes or groups that apply to this option -->
            <Value>gEU,gSchengen,AD</Value>
            <DisplayText>Country of issue of passport of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>ID_PASSPORT_EXPIRY_DATE</Name>
            <ParamType>checkin</ParamType>
            <DisplayText>Expiry date of passport of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>PAX_DATE_OF_BIRTH</Name>
            <ParamType>checkin</ParamType>
            <DisplayText>Date of birth of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>INFO_ADDITIONAL</Name>
            <!-- 'info' parameters are just extra information, rules, or terms and conditions from the airline -->
            <ParamType>info</ParamType>
            <DisplayText>Online checkin is not available for unaccompanied minors and disabled passengers</DisplayText>
          </ParameterOptionItem>
        </ParameterOptionItemList>
      </ParameterOption>

      <!-- Option where traveller of age 14-99 has (and can check in with) national ID issued by Spain -->

      <ParameterOption>
        <ParameterOptionItemList>
          <ParameterOptionItem>
            <Name>TRAVELLER_AGE_RANGE</Name>
            <!-- 'condition' parameters specify restrictions to this option. They are not required by the airline -->
            <ParamType>condition</ParamType>
            <Value>14-99</Value>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>ID_NATIONAL_NUMBER</Name>
            <ParamType>checkin</ParamType>
            <DisplayText>National ID number of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>ID_NATIONAL_COUNTRY_OF_ISSUE</Name>
            <ParamType>checkin</ParamType>
            <!-- Restriction of Spain -->
            <Value>ES</Value>
            <DisplayText>Country of issue of national ID of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>ID_NATIONAL_EXPIRY_DATE</Name>
            <ParamType>checkin</ParamType>
            <DisplayText>Expiry date of national ID of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>PAX_DATE_OF_BIRTH</Name>
            <ParamType>checkin</ParamType>
            <DisplayText>Date of birth of the traveller</DisplayText>
          </ParameterOptionItem>
        </ParameterOptionItemList>
      </ParameterOption>

      <!-- Option where traveller of any age has (and can check in with) passport NOT issued by EU, EU Schengen, or Andora -->

      <ParameterOption>
        <ParameterOptionItemList>
          <ParameterOptionItem>
            <Name>ID_PASSPORT_NUMBER</Name>
            <ParamType>checkin</ParamType>
            <DisplayText>Passport number of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>ID_PASSPORT_COUNTRY_OF_ISSUE</Name>
            <ParamType>checkin</ParamType>
            <!-- 'non-' indicates negation; it is prefixed to country, country-group, or collection[] codes. E.g. non-gEU, non-AD, non-[gEU,gSchengen,AD] -->
            <Value>non-[gEU,gSchengen,AD]</Value>
            <DisplayText>Country of issue of passport of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>ID_PASSPORT_EXPIRY_DATE</Name>
            <ParamType>checkin</ParamType>
            <DisplayText>Expiry date of passport of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>PAX_DATE_OF_BIRTH</Name>
            <ParamType>checkin</ParamType>
            <DisplayText>Date of birth of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>ID_VISA_NUMBER</Name>
            <ParamType>checkin</ParamType>
            <DisplayText>VISA number of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>ID_VISA_COUNTRY_OF_ISSUE</Name>
            <DisplayText>Country of issue of VISA of the traveller</DisplayText>
          </ParameterOptionItem>
          <ParameterOptionItem>
            <Name>ID_VISA_EXPIRY_DATE</Name>
            <ParamType>checkin</ParamType>
            <DisplayText>Expiry date of VISA of the traveller</DisplayText>
          </ParameterOptionItem>
        </ParameterOptionItemList>
      </ParameterOption>
    </ParameterOptionList>
  </CheckinAvailabilityPlane>
</CommandList>

Some of the above information may be used as API (Advance Passenger Information) by the airline. However, in every <ParameterOption> we include everything that is required for a successful online check-in regardless it is going to be used as an API or not.