Searching for Universal Records
As of December 2019, new Universal API customers must be provisioned to use UniversalRecordSearch in production. This transaction is available to new customers on pre-production.
If the Universal Record (UR) record locator is not known, it can be searched using data from a PNR that is contained within the UR. The same search can be used to locate more than one Universal Record that meets a specific criteria, such as PNRs issued by the same travel agent or PNRs with past date segments.
Request
UniversalRecordSearchReq in the UniversalRecordSearchService can be used to retrieve a list of Universal Records that meet the request parameters.
Search Criteria
Search criteria can be requested at either Universal Record (UR) level or the PNR level with data from a one or more PNRs contained in a Universal Record. Criteria can also include a combination of data from both the Universal Record level and the PNR level. Any/all parameters for air, car, hotel, rail can be used in any combination in Universal Search Request.
Both Universal Records that contain PNRs booked directly through Universal API or PNRs that have been booked externally with a Universal API provider can be searched. If PNR data is included in the search criteria that is not located within Universal API, the system automatically searches Universal API's providers' systems for the PNR. However, if the PNR was not booked through Universal API, a ProviderCode and ProviderLocatorCode must be included in the request.
Note: External search functionality is currently available only for Galileo and Apollo PNRs.
UR-Level Search Criteria
Universal API provides the ability to search Universal Records (UR) across Agency, Branch, or Branch Group, based on the permissions and security level of the Agent. An agent must have one of the following security levels to perform a UR search across profiles:
- Admin level
- ME level
- Agency level
- Bridge Branch level
- Branch level
- Agent level.
Search criteria at the UR level is contained in the attributes of UniversalRecordSearchReq:
-
The ActionDate when the reservation was created.
- The RecordStatus:
'All' search for all past, current, or future reservation segments.
'Past' search for reservations that have all segments in the past. If the Universal Record has been archived, it is not returned unless the requester has Agency Administration level access or higher.
'Current' search for reservations that have at least one segment that is a current or future date.
'Cancelled' search for reservations that have all segments canceled.
-
The ProviderCode for the GDS or other provider source. If a provider code is included in the request:
-
At least one additional search criterion must also be included in the request.
-
If an additional UR-level criterion is included in the request, but no PNR-level criteria are included, all product (segment) type data is returned.
-
If PNR-level criteria are included, only the specified product (segment) type data is returned. For example, a request with a ProviderCode and AirReservationCriteria returns only responses for Air PNRs for the specified provider; Hotel, Vehicle, or Rail PNRs are not included.
-
Only PNR data for the specified provider is returned. Therefore, if a Universal Record contains PNRs from more than one provider, only PNRs from the requested provider are returned in the response.
-
If the ProviderCode is set to "SDK" only Universal Records with externally reserved SDK segments are returned in the response. However, the ProviderLocatorCode must also be included with the ProviderCode to search for an external SDK segment.
This search functionality can be used to search for external PNRs that are candidates for being imported into Universal API. The search returns a list of SDK PNRs that match the search criteria; to retrieve the actual PNR data, the PNR must then be imported.
-
-
The ProviderLocatorCode, which is the provider's record locator code for the PNR. If a provider locator code is included in the request:
-
The search is made only by provider locator code. All other search criteria are ignored.
-
The response returns only PNRs in a Universal Record that contain the requested locator code. If a UR has at least one PNR with the provider locator code that matches the requested locator code, the response returns that UR but shows only the products associated with the matching provider reservation. Any other PNRs contained in the same UR are not returned in UniversalRecordSearchRsp.
-
Searching Universal Records based on ProviderLocatorCode is restricted to searching for Universal Records that exists for that provider locator code. If the URs to be searched are outside the Agent’s permission levels, then an error is returned: Not Authorized to view this UR.
-
-
RestrictToProfileID allows the search to be narrowed further, to only an Agency, Branch, or Branch Group.
-
Search only for Universal Records that contain passive segments.
-
The TicketStatus can be used to search for Universal Records (UR).
TicketStatus has the enumerations:
- Code="U" Description="Unticketed"
- Code="T" Description="Ticketed"
- Code="V" Description="Voided"
- Code="R" Description="Refunded"
- Code="X" Description="eXchanged"
- Code="Z" Description="Unknown/Archived/Carrier Modified"
- Code="N" Description="Unused"
- Code="S" Description="Used"
Passive segments can also be added as a criterion at the PNR level. Adding a passive only searches all product segments in the UR. Add a PassiveOnly search at a product (segment) level permits only a product type to be searched. For example, Passive only searches can be designated for hotel segments, but not for any air segments in a PNR.
PNR-Level Search Criteria
Search criteria at the PNR level is made using the ReservationSearchModifiers child. A PNR-level search can be made with or without a specified PNR.
-
If a Provider Code and/or Provider Locator Code are specified in the request, only PNR data for the specified provider or PNR locator that meets the search parameters are returned.
-
If no Provider Code or Provider Locator Code is included all Universal Records that meet the search parameters are returned, regardless of provider or provider locator code.
Attributes and children for ReservationSearchModifiers include or exclude specific types of data from the response for each PNR to:
-
Include all names of travelers in the PNR, instead of the default primary booking traveler only. If @IncludeAllNames is set to 'false' or is not specified, additional traveler names are included in the search request in TravelerCriteria, only if the additional traveler's first and last name are included in the request; wildcards are not support for additional travelers.
-
Include information about the agent who created, modified or ticketed the PNR.
-
Limit the number of results returned, particularly in more general searches that may return a large result set. The StartFromResult attribute can be used to browse beyond the maximum number of results specified.
-
A child element, TravelDate, also supports searches for any travel date that occurs at any point between the start and end of the trip. At this level, TravelDate dates or date ranges apply to any air departure date, hotel check-in date, vehicle pick-up date, or rail trip departure date contained within a PNR.
Date ranges can also be included in the search if the exact date is not known. Specific date and date range requests are mutually exclusive; only one type of date request can be used for the search.
Dates can also be applied at the product (segment type) level for air, hotel, vehicle, or rail segments. However, if both a PNR-level TravelDate and a product-level segment date are sent in the request, an error is returned. For example, if both a PNR travel date (TravelDate) and an air departure date (ReservationSearchModifiers/SearchCriteriaGroup/AirReservationCriteria/DepartureDate) are included in a search request the request fails and an error is returned.
Within the SearchCriteriaGroup child of ReservationSearchModifiers traveler travel segment criteria can be requested.
-
TravelerCriteria, including a traveler's first name, last name, phone number, Traveler ID, and VIP status. Unless otherwise specified, the traveler data can be either for the booking traveler or a secondary traveler in the PNR.
-
Name searches can include wildcards, and can be made by:
-
First and last name. Example: Smith, John.
Last names must include at least two letters. -
Last name only. Example: Smith.
-
Last name with wild card: Sm*.
Wildcards cannot be used at the beginning or middle of a name. Wildcards are permitted only at the end of a name. -
Full last name and first name with wild card: Smith, J*.
First names must include at least one letter for wildcarding. -
First and last names with wildcard: Sm*, J*.
- When searching by last and first name, it can result in a response that has multiple URs with different Traveler IDs. However, a search by Traveler ID, the response will be more specific.
-
Phone searches are made for the booking traveler only, and can be made for any type of phone number included in the PNR. Wildcards are not supported for phone numbers.
- UR can be searched by Traveler IDs, so the response only includes Travelport Universal Records that match a specific Traveler ID.
Note: Traveler ID search does not include Worldspan (1P), and Airline Content Hub (ACH). -
Functionality was added to return canceled Universal Records based on a Search by Name, provided that the Universal Record contains an air segment. Previously, only active Universal Records were returned.
-
AirReservationCriteria, including origin location, destination location, departure and arrival dates or date ranges, flight numbers, carrier (supplier), and passive air segments.
-
Origin and destination locations currently support airport codes. If a city code is sent, PNRs for all airports associated with that city are returned.
-
If both a departure date and travel date are present in the request, the
-
HotelReservationCriteria, including location, check-in and check-out dates or date ranges, flight numbers, hotel chain vendor (supplier) code, the hotel property code (HotelCode), the supplier's confirmation number, and passive hotel segments.
-
VehicleReservationCriteria, including location, pick-up dates or date ranges, the location number for vehicle pick-up, the supplier's confirmation number, and passive vehicle segments.
-
RailReservationCriteria, including the departure or arrival date, or date range, for the rail trip; the departure or arrival date, or date range, for a rail segment within the trip; the journey origin or destination, or rail location origin or destination; and passive rail segments.
Airport or city codes can be used for the hotel location. If a city code is sent, PNRs for all airports associated with that city are returned.
Airport or city codes can be used for the vehicle location. If a city code is sent, PNRs for all airports associated with that city are returned.
Note:
The following search types are not yet implemented, and are planned for later releases:
-
ClientID, which searches by the profile's Client ID.
-
SearchAccount, which searches by Branch ID and Client ID
-
SearchAgent, which searches by a specific agent in an associated Client ID.
-
ExternalSearchIndex, which supports searching within a provider's system.
-
GroundReservationCriteria, as ground reservations are not yet implemented.
-
UniversalRecordSearchModifiers attributes ExcludeAir, ExcludeVehicle, and ExcludeAirHotel, exclude PNR segments with specified product type from the search results.
Note: Ground and Rail reservations cannot be excluded.
Open-Ended UR Searches
Open-ended UR searches are disabled as of Universal API release 201.3 Release 20.1. All seraches now provide upfront validation of a Universal Record search to reduce the impact of open-ended UR Searches . Open-ended searches can impact the stability of the system due to the significant time required for execution. If search criteria are not met, UniversalRecordSearchRsp returns one of the following errors based on the issue:
- When only the Last Name is in Traveler Criteria and other criteria are null:
"At least one additional parameter should present to search along with 'LastName'." - When only the Carrier Code is in Air Reservation criteria and others are null:
"At least one additional parameter should be present to search by 'CarrierCode'." - When only the provider and target banch and others are null:
"Incomplete search criteria, please add more criteria to the UR request."
Response
UniversalRecordSearchRsp returns multiple UniversalRecordSearchRsp elements. Each UniversalRecordSearchRsp contains high-level data from a single UR that contains the requested data in or more of its PNRs.
For more detailed data about a PNR, a specific UR retrieve request can be made using the UR's record locator.
Attributes of UniversalRecordSearchRsp contains one or more UniversalRecordSearchResult child elements. Each child corresponds to an associated PNR.
Each instance of UniversalRecordSearchResult returns attributes to indicate the following UR data:
-
The UniversalRecordLocatorCode for the Universal Record that contains the response PNR. If the trip associated with the PNR was saved, but not reserved, a SavedTripLocatorCode is returned.
-
The date the booking was created.
-
The earliest travel data in the booking.
-
The TicketStatus.
For each UniversalRecordSearchResult, one or more ProductInfo child elements may be returned, corresponding to each PNR segment contained within the parent UR.
For each ProductInfo child element contain in UniversalRecordSearchResult, the following PNR data is returned:
-
The ProductType , which is the type of segment associated with the PNR: Air, Vehicle, Hotel, Ground, Rail, or Other.
-
The VendorCode, which is the supplier's code. For Air, Car, and Hotel segments this code is the IATA code. Ground and Rail suppliers do not have IATA codes.
-
The ProviderCode, which indicates the GDS or other provider system that issued the reservation.
-
The ProviderLocatorCode, which is the record locator issued for the PNR by the provider.
-
A ticketing indicator, to note whether the PNR segment has already been ticket. Applies to Air segments only.
-
The name of the traveler associated with the PNR For air bookings only, the date that the reservation was ticketed.
- The Name element also contains the optional TravelerProfileID attribute, which returns the Traveler ID.
Universal Record (UR) Search responses returns traveler names and information for canceled air segments.
The Search by Name functionality (@IncludeAllNames) can be used in the UR Search request for canceled as well as active Universal Records. Note that the provider's record locator (@VendorCode) is not returned in the UR Search response. For example:
<UniversalRecordSearchResult UniversalRecordLocatorCode="DX9XR3" CreatedDate="2015-02-10T19:16:42.000+00:00" Ticketed="Not Applicable" RecordStatus="Canceled" TicketStatus="Not Applicable"/>
<ProductInfo ProductType="Air" ProviderCode="1G" ProviderLocatorCode="4XJ9CE">
<Name Prefix="Mr" First="George" Last="WAIKIKI"/>
</ProductInfo>
</UniversalRecordSearchResult>
This enhancement applies only to Universal Records that contain an air booking (ProductType="Air"). If the Universal Record contains only non-air segments, such as hotel or vehicle bookings, the traveler's name is not returned in the Canceled UR data.
Next Steps
If more detailed data is desired for a specific reservation, a follow-on request can be made for specific UR retrieve request can be made using the UniversalRecordLocatorCode.
Errors
If UniversalRecordSearchReq does not find any matching provider reservations in the UR database, the following error is returned: PNRSvc error 6001 Could not retrieve PNR. No records found.