Retrieving a Universal Record with a Known Locator

UniversalRecord.xsd

Create Reservation > Universal Record Retrieve OR
Universal Record Import >  Universal Record Retrieve

If the Universal Record locator code is known, a Universal Record can be retrieved by using the Universal Record Retrieve request. Whenever possible, any PNR data stored in the Universal Record is validated against the PNR data in the provider's system.

Notes:

Schema

See the following transactions for Retrieving a Universal Record:

Request

Note: Universal API supports retrieval of group bookings. This is limited functionality. This functionality is controlled by a PCC switch. Please contact your Travelport representative or open an Incident Report to activate this enhancement.

  1. Send UniversalRecordRetrieveReq with the following minimum information:.

    • Credentials required for access. To retrieve a Universal Record, the UserID in the Credentials must match the credentials used to create the Universal Record or be an ID that has branch access to the original ID.

    • A valid @UniversalRecordLocatorCode.

  2. Enter @TravelerLastName and ProviderReservation @ProviderCode and @ProviderLocatorCode to retrieve a PNR and use the traveler last name for validation.

    3. Notes: @TravelerLastName is an attribute of UniversalRecordRetrieveReq.

    To retrieve the PNR and validate with a last name, the following data is required:

    • @ProviderCode: Supported for 1G, 1V, 1P.
    • @ProviderLocatorCode: The provider's PNR record locator. See the additional information returned in the response section when the @ProviderLocatorCode is added in the request.

    If a match is found to an existing PNR, Universal API returns the Universal Record that corresponds to the PNR. If a match is not found, Universal API returns an error. If a record exists, but a match is not found, an error is returned: No matching traveler found.

    If the PNR is already associated to a Universal Record (UR), the UR is retrieved. If the PNR is not associated to an existing UR, and new UR is created.

    This functionality is not supported RCS. However, if a Universal Record contains aggregated content from a GDS provider (1G, 1V, 1P) and non-GDS provider (RCS), the non-GDS data is synchronized with the provider.

    Note: Prior to Universal v49.0 with Universal API release 19.2.1, ACH was not supported: Release 19.2

    • When creating a booking, sometimes the booking is created on the vendor system, but external issues prevented a Universal Record to be created via Universal API.

    • Universal v49.0 provides the ability to retrieve a booking on a vendor system in ACH and add to a workflow.

    • This reduces the number of orphan bookings and also allows customers the ability to better service their bookings, because they are now accessible through a Travelport product.

    This functionality is available on Universal Record Retrieve with Universal v49.0 and above. To retrieve the ACH PNR, the following attributes are required:

    • @TravelerLastName
    • ProviderReservation @ProviderCode and @ProviderLocatorCode

    The following example shows URRetrieve request to retrieve ACH orphan PNR, with the required highlighted fields, along with ProviderCode and ProviderLocatorCode:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
     <soapenv:Body>
      <univ:UniversalRecordRetrieveReq TargetBranch="123" TravelerFirstName="Juan" TravelerLastName="Test" xmlns:univ="http://www.travelport.com/schema/universal_v49_0" xmlns:com="http://www.travelport.com/schema/common_v49_0">
       <com:BillingPointOfSaleInfo OriginApplication="UAPI"/>
       <univ:ProviderReservationInfo ProviderCode="ACH" ProviderLocatorCode="123ABC" SupplierCode="XX"/>
      </univ:UniversalRecordRetrieveReq>
     </soapenv:Body>
    </soapenv:Envelope>

  3. Enter @ViewOnlyInd to view a PNR in Universal Record format without saving it as a Universal Record.

    4. A PNR can be viewed in UR format without saving it as a Universal Record. In the request:

    • Set @ViewOnlyInd to "true".
    • Include ProviderReservationInfo/@ProviderCode and @ProviderLocatorCode.

    If the PNR is not part of an existing UR, it is retrieved and returned in the response, but not saved in the Universal API database. If the PNR is part of an existing UR, ViewOnlyInd is ignored and the UR is retrieved and synchronized with the PNR.

    Each time a request is sent to view a PNR, Universal API retrieves the latest details of the PNR from the provider and returns them in UR format in the response.

    If @ViewOnlyInd is not sent in the request, the attribute is considered "false" and Universal API retrieves the UR and synchronizes it with the PNR.

  4. Enter @RetrieveProviderReservationDetails to display provider details.

    5. RetrieveProviderReservationDetails is a Boolean attribute.

    • When set to false (default), the response displays provider details using UniversalRecord/ProviderReservationInfo/ProviderReservationDetails.
    • When set to true, ProviderReservationDisplayDetailsList displays in the response in UniversalRecord/ProviderReservationInfo. This element displays some details of the PNR elements that are not otherwise returned in the Universal Record.

    Universal versions prior to v29.0 will not return the ProviderReservationDisplayDetailsList element.

  5. Optionally, set @ReturnUnmaskedData="true" Release 20.3
  6. Optionally, set @ReturnAmenities="true" to return Routehappy content. Release 24.3

Response

During the retrieval process, Universal API synchronizes any PNR data in the Universal Record with the available data from the respective providers' latest versions of the PNR. However, Universal API's ability to update a given Universal Record and associated PNRs is dependent on the provider's or supplier's support of this functionality. Suppliers such as Low Cost Carriers in ACH and rail providers in RCS do not typically support strong modify functionality, and may synchronize only a limited amount of the PNR data.

UniversalRecordRetrieveRsp returns the requested Universal Record (UR) and synchronizes data in the UR with the provider PNR.

When the Universal Record is retrieved and synchronized with the PNR, the ticket number from the PNR is added to UniversalRecord/DocumentInfo/TicketInfo @Number and a reference to the associated pricing information (i.e., the Stored Fare) is added to UniversalRecord/DocumentInfo/TicketInfo @AirPricingInfoRef, if the pricing information has an associated ticket number. The association of ticket number and pricing information ensures that any TargetBranch who can retrieve the UR can see the Ticket number, even if that TargetBranch cannot view ticket details and ETR retrieve fails. Additional Net Ticket Details from the PNR are also synchronized and displayed in the Universal Record in UniversalRecord/AirReservation/AirPricingInfo/FareInfo:

  • Tour Code

  • Car Code

  • Value Code (never populated)

  • Commission (optional). Only fare-level commissions are supported as ticketing modifiers, so @Level must be "Fare". @Type can be either "Flat" or "PercentBase". If "Flat", @Amount must be present and CommPercentage="9999999". If "PercentBase", @Amount=0 and CommPercentage=1 to 100.

When the ProviderLocatorCode is included in the request:

  • For new tickets, Universal API determines the ticket status, and returns the status in the UniversalRecordRetrieveRsp/UniversalRecord/AirReservation/DocumentInfo/TicketInfo@Status. The ticket status for existing tickets, including coupon information, is also returned in TicketInfo@Status.

  • For Exchanged tickets, along with the status information update, UniversalRecordRetrieveRsp, UniversalRecordImportRsp, and AirRetrieveDocumentRsp retrieves the original ticket number in the path /UniversalRecord/AirReservation/DocumentInfo/TicketInfo/ExchangeTicket@Number.

    • The status of the new exchanged ticket is ‘O’ – Open for use. But, the retrieve response also contains the original ticket number information.

    • The status of the original ticket number is ‘E’ – Exchanged.

If the FOP found in the Universal Record is not returned in the PNR, Universal API validates whether the FOP in the Air Reservation is referenced in EMDSummaryInfo Payment. If it is, Universal API removes PROVIDERRESERVATIONINFOID from the FOP and displays the FOP in the Air Reservation without ProviderReservationInfoRef. If the FOP in the Air Reservation is not referenced in EMDSummaryInfo Payment, the FOP is removed from the UR.

Note: In Universal v32.0, when a Universal Record (UR) containing a Miscellaneous Form of Payment was returned in the UniversalRecord element in any Universal API response, the MiscFormOfPayment@Text attribute was partially masked.

  • Although this the correct response when the MiscFormOfPayment@Category = ‘FreeFormCreditCard’ it hampered the user’s ability to obtain complete information in other scenarios. For example:

    • When the Category was Exchange and Text contained the exchanged TicketNumber, the exchanged TicketNumber was masked.

    • When the Text attribute is masked only when there is any SSR present in the PNR. Even when MiscFormOfPayment@Category = ‘FreeFormCreditCard’ the Text attribute is unmasked if there is NO SSR present in the PNR.

  • With Universal v33.0, Universal API now:

    • Partially masks MiscFormOfPayment@Text when MiscFormOfPayment@Category = ‘FreeFormCreditCard’ or ‘CreditCard’ regardless of whether there is an SSR present.

    • Unmask MiscFormOfPayment@Text when MiscFormOfPayment@Category NOT = ‘FreeFormCreditCard’ or ‘CreditCard’ regardless of whether there is an SSR present.

Updated seat assignment values that have been synchronized with the carrier’s system are returned. If a seat assignment is added or modified outside of Universal API, the synchronized response reflects the modification in Universal API when the UR is retrieved.

When a UR that contains an ATPCO-filed Optional Service is retrieved or synchronized, and the ASVC SSR Status has changed, @ServiceStatus is updated to match the ASVC SSR.

When Optional Services are sold through Terminal Entry (native mode), Electronic Miscellaneous Documents (EMDs) issued for the Optional Services by the provider are synchronized with the Universal Record (UR) when the UR is retrieved or imported. The issuance number and coupon number from the provider EMD are stored in the UR in AirReservation/OptionalService/ServiceData in @EMDSummaryRef and @EMDCouponRef.

In OptionalServices/OptionalServicesTotal:

  • Universal API returns the total for the Optional Services, including taxes.
  • For ATPCO-filed Optional Services, the total of all Optional Services is added by Universal API and returned in OptionalServicesTotal.
  • When ACH LCC and API carrier Optional Services are returned from multiple carriers and the currency codes are the same, Universal API returns BasePrice, Taxes, Fees, and TotalPrice in OptionalServices/OptionalServicesTotal.
  • When ACH LCC and API carrier Optional Services are returned from multiple carriers and the currency codes are the different, Universal API does not return BasePrice, Taxes, or TotalPrice in OptionalServices/OptionalServicesTotal. Instead, the ApproximateTotalPrice and ApproximateBasePrice are returned in OptionalServicesTotal based on the default currency code of the TargetBranch (WAB).
  • If Optional Services are returned from multiple providers in the response, Universal API returns OptionalServices/OptionalServicesTotal with the combined price.
  • If Optional Services are returned from multiple providers in the response and the currency codes are different, the ApproximateTotalPrice and ApproximateBasePrice are returned in OptionalServicesTotal based on the default currency code of the TargetBranch (WAB).

A cancelled OptionalService is deleted from the Universal Record when the Universal Record is synchronized, and is no longer returned in the Universal Record Retrieve response with @ServiceStatus=”Canceled”.

Baggage information attributes return in the UniversalRecordRetrieve response on Galileo (1G): Release 23.3

  • UniversalRecordRetrieveRsp/UniversalRecord/AirReservation/OptionalServices/OptionalService

    • @TotalWeight

    • @FirstPiece

    • @LastPiece

  • This is limited release functionality. Please contact your Travelport representative to activate this enhancement.

The CurrencyType in AirPricingModifiers is passed to the provider, which impacts the currency that is returned for Equivalent Base Price, Base Price, Taxes, and Total Price. The CurrencyType modifier specifies the currency that is to be used for settlement. The provider may restrict which currencies are available based on a variety of factors including origin, destination, and agency location. The requested currency is reflected in the EquivalentBasePrice, BasePrice, Taxes, and TotalPrice, if it is available.

When @ViewOnlyInd="true" is sent in the request, the following elements or attributes of UniversalRecordRetreiveRsp/UniversalRecord contain the static value of "999999":

  • @LocatorCode
  • /AirReservation @LocatorCode
  • /HotelReservation @LocatorCode
  • /VehicleReservation @LocatorCode
  • /PassiveReservation @LocatorCode
  • /RailReservation @LocatorCode

If the PNR is part of an existing UR, ViewOnlyInd is ignored and a warning is returned: "‘ViewOnly’ retrieval of a PNR already existing in a UR is not possible. Sync is done”

If ViewOnlyInd="true" and the UniversalRecordLocatorCode is provided, ViewOnlyInd is ignored and a warning is returned: “‘ViewOnly’ retrieval of an UR is not possible. Sync is done”

The AgencyInfo element that contains AgentAction is not returned in the response.

If a Dynamic WAB is created as part of a view-only retrieve request, it is not stored.

The OB fees for a Universal Record are returned after the Universal Record is ticketed with a credit card or debit card form of payment. Refer to OB Fees for more information about these fees and their subcodes.

ACH Taxes and Fees Breakdown

For ACH carriers that include the taxes and fees within the base fare at the itinerary level, Universal API provides a breakdown of the taxes and fees included in the base fare when this information is provided by the carrier. In AirCreateReservationRsp/UniversalRecord/AirReservation and /AirReservation/AirPricingInfo, each TaxInfo or FeeInfo element contains the attribute @Text, which returns any freeform text information provided by the supplier, and the element IncludedInBase, which provides the breakdown of the taxes and fees. IncludedInBase has the attribute @Amount, which shows the amount included in the base fare for the specific fee or tax. This information is provided by default anytime it is available from the ACH carrier.

Approximate Taxes Release 23.4

The returns approximate values in a booking retrieve response so that customer system calculations. which are dependent on the approximate values, don't fail when a booking is retrieved.

/UniversalRecord/AirReservation/AirPricingInfo @ApproximateTaxes

This is limited release functionality. Please contact your Travelport representative to activate this enhancement.

Routehappy Amenities Release 24.4

Air v53.xsd expands on the existing Routehappy flight amenity content returned in the AirCreateReservation and UniversalRecordRetrieve transactions by extending the data to each leg of a direct flight.

Note: This is limited release functionality. Contact your Travelport representative for further information.

Troubleshooting

If you receive the error No provider reservation to import when trying to retrieve or import a PNR that does have a segment, it means that the segment is in a non-standard format that Universal API does not recognize. You can force the import/retrieve of the PNR by adding a retention segment in a format that Universal API recognizes (such as a TVL segment).

Exceptions

The following data is not validated against the Galileo system when a UR is retrieved:

  • Phone numbers for non-primary booking travelers. Galileo associates phone numbers with a PNR, not with a specific traveler.

  • Email addresses for non-primary booking travelers. Galileo associates email addresses with a PNR, not with a specific traveler.

  • Form of payment. In Galileo, the credit card form of payment is masked when a PNR is retrieved. Therefore, the last four unmasked digits of the credit card are compared against the last four digits of the booking credit card.

  • Form of payment. In Worldspan, the credit card form of payment is masked when a PNR is retrieved. Therefore, the last four unmasked digits of the credit card are compared against the last four digits of the booking credit card. If they match, the booking credit card is used.
  • Universal API does not return the FareRuleKey in the Worldspan UniversalRecordRetrieveRsp.

For a more complete list of functionality available from various ACH carriers, see ACH Carriers Functionality. Because functionality for carriers may be subject to change, always confirm functionality directly with the ACH carrier before implementation.

  • Form of payment. For all ACH carriers, if the credit card returned in the retrieve is different, a warning message is provided. However, the new card is not added because it is masked in the ACH Retrieve.

  • Jet2 (LS) has very limited retrieve capability. Price, form of payment, and Booking Traveler address details are not returned.

  • easyJet (U2) does not:

    • Support Retrieve after cancel. An error is returned.

    • Return full details on Optional Services booked directly with the carrier.

  • ApproximateBasePrice and ApproximateTotalPrice are impacted by the CurrencyType.

  • If the sum of the passenger level fees is different than the itinerary level fees returned by ACH in Universal v.30.0 and greater, but the fee type is the same, a warning is returned: Passenger type level fees are informational only, and may not match with those returned at the itinerary level.

  • Universal API 19.2.1 release provides the ability to retrieve a booking on a vendor system in ACH and add to a workflow. This reduces the number of orphan bookings and also allows customers the ability to better service their bookings, because they are now accessible through a Travelport product. Release 19.2

  • For rail segments, the following data is synced when the UR is retrieved:

  • Customer Loyalty information. The customer loyalty information is also saved in the UR History.

  • For rail segments, the following data is not validated against the RCS system when a UR is retrieved:

    • Booking Traveler name.

    • Booking Traveler phone number.

    • Booking Traveler email address.

    • Booking Traveler address.

    • Form of payment. A warning message is returned to the client if the form of payment in the Universal Record does not match the form of payment found in the rail distributor's booking.

    • Payment

  • "Businessi" is ignored and Beneif is returned in the CabinClass attribute of RailFare or RailAvailInfo, and also return a warning in the response.

  • If RCS does not return FareClass in the response, CabinClass="Economy" will be mapped. In older schemas, CabinClass= "Standard" is mapped.

  • With Rail v35.0 and Universal v35.0 and later, because the class code and cabin class can differ for each train segment, the @ClassCode and @CabinClass are returned in the Rail Create Reservation Response, Universal Record Retrieve Response, and Rail Exchange Response (/UniversalRecord/RailReservation/RailJourney/RailSegment @ClassCode and @CabinClass).