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:
-
If the UR locator code is not known, see Searching for Universal Records.
-
You can retrieve bookings by other locators, such as the host locator. E.g.,
-
Copy
Retrieve Booking by Host Locator - 1G
<UniversalRecordRetrieveReq xmlns="http://www.travelport.com/schema/universal_v42_0" TraceId="" AuthorizedBy="Travelport" TargetBranch="P1234567">
<BillingPointOfSaleInfo xmlns="http://www.travelport.com/schema/common_v42_0" OriginApplication="uAPI" />
<ProviderReservationInfo xmlns="http://www.travelport.com/schema/universal_v42_0" ProviderCode="1G" ProviderLocatorCode="ABC123" />
</UniversalRecordRetrieveReq>
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.
- 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.
-
Enter @TravelerLastName and ProviderReservation @ProviderCode and @ProviderLocatorCode to retrieve a PNR and use the traveler last name for validation.
-
With the release of Universal API 20.4.2, Import Booking and Booking Retrieve support requests when the booking is a group (e.g., 10 passengers or more). The universal record locator and basic booking details are returned in the response.
-
Multiple retrieval of the PNRs is restricted due to the extended time it takes to retrieve group bookings, and an error message displays: "Retrieve Group Booking already in progress. Please try again later."
-
When the UR Import is successful, the associated cache, and expiration timeframe, is cleared.
-
- @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.
-
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.
- @TravelerLastName
- ProviderReservation @ProviderCode and @ProviderLocatorCode
-
Enter @ViewOnlyInd to view a PNR in Universal Record format without saving it as a Universal Record.
- Set @ViewOnlyInd to "true".
- Include ProviderReservationInfo/@ProviderCode and @ProviderLocatorCode.
-
Enter @RetrieveProviderReservationDetails to display provider details.
- 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.
- Optionally, set @ReturnUnmaskedData="true" Release 20.3
- Optionally, set @ReturnAmenities="true" to return Routehappy content. N
Notes: @TravelerLastName is an attribute of UniversalRecordRetrieveReq.
To retrieve the PNR and validate with a last name, the following data is required:
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
This functionality is available on Universal Record Retrieve with Universal v49.0 and above. To retrieve the ACH PNR, the following attributes are required:
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>
A PNR can be viewed in UR format without saving it as a Universal Record. In the request:
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.
RetrieveProviderReservationDetails is a Boolean attribute.
Universal versions prior to v29.0 will not return the ProviderReservationDisplayDetailsList element.
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.
-
As of Universal v48.0, the @Number, @TicketIssueDate, @TicketingAgentSignOn, and @IATANumber return in a single response as part of /TicketInfo and /ConjunctedTicketInfo in UniversalRecordRetrieveRsp/UniversalRecord/AirReservation/DocumentInfo/. Release 19.1
-
Schedule changes can be accepted for one or more air segments in the Universal Record. Ticket information displays regardless of modifications to segments or the filed fare, cancellation of the filed fare, or cancellation of the Universal Record.
-
Synchronization of the Payment element in the UR Retrieve response is not supported. If a booking that incurred a charge is modified outside of Universal API, the original Payment data remains in Universal API, and may not match the updated Payment data in the carrier’s system.
-
The applied residency type returns in booking and ticketing retrieve responses, so that the nationality from the applied residency type by passenger line or data can be applied in a future exchange. This is useful because of taxes based on nationality. For example, Mexico has a tax for foreigners and Argentina has two taxes for residents. Release 23.1AirSolutionsChangedInfo/AirPricingSolution/AirPricingInfo/PassengerType @ResidencyType
-
Fare Guarantee information to help identify the source of the quoted fare may be returned. See Fare Guarantees for details.
-
When any Universal request causes synchronization of Universal Record with host PNR, if the hotel segment in the Universal Record does not have property address, phone number, or property name, Universal API adds these details to the hotel reservation based on the hotel property number in the Universal Record. This information is added in the UniversalRecord/HotelReservation/HotelProperty element.
-
If the Universal Record was imported and that PNR's owning PCC did not exist in Universal API, a dynamic target branch was automatically created for that PCC. The dynamic target branch information displays in UniversalRecord/AgencyInfo/AgentAction. For more information about how the dynamic target branch is created, see Importing PNRs.
-
The country code of the active PCC is returned as of Universal v48.0 to differentiate ARC (used for 1V reconciliation) PCCs from BSP (use for 1G reconciliation) PCCs, and from Worldspan (1P) PCCs. With this information, Travelport can enable the correct processing of reissues in Galileo, in US PCCs, so that when repricing, results display in a netted (ARC) or non-netted (BSP) format. Release 19.1
-
For Galileo or Apollo, if invoice data is present, it is returned in the UniversalRecord/InvoiceData element.
-
For Galileo or Worldspan, if the PNR has associated Miscellaneous Change Orders (MCOs), basic MCO information is imported. See Miscellaneous Change Orders for details.
- The @NameNumber attribute ensures the Universal Record Retrieve and Booking Retrieve (ETR) transactions add the ability to display Passenger name number for each passenger (Booking Traveler), which enables the ability to work with the booking in other channels. Release 18.3
This information returns in all responses where Booking Traveler information is returned.
This feature allows customers to identify the specific passenger location in a booking to be used when cryptic entries must be used in back-end processing.
When a PNR is split, the Booking Traveler element still stays in the UR. The name number is updated to reflect the GDS values and the name number of the passenger, who are removed from the PNR, and is removed from the I Booking Traveler.
Example:
<com:BookingTraveler Key="Qm9va2luZ1RyYXZlbGVyMQ==" TravelerType="CNN" NameNumber=”1.1”>
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.
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.
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.
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).