Profile Retrieve

Profile Retrieve retrieves not only details of the agent, but information about its parent branch and in turn its parent, all the way to its root ancestor, which may be an agency, agency group, or account. This will enable the application to fetch and cache data (like profiles and templates) for the agent’s session.

A user can retrieve one and only one profile per request, by its unique ID.

If an agent profile is being retrieved and that agent is emulating into another work area (if TargetBranch in BaseReq is not null), then the profile information in the response is in the context of the emulation. That is, the emulated work area is returned as the agent’s parent, for the purpose of the parent summary or parent inherited information.

Schema

Profile Retrieve is within uProfile.xsd. See the following transactions for Profile Retrieve:

Request

The ProfileRetrieveReq allows you to retrieve profiles.

A user may retrieve one and only one profile in a given request. When requesting a profile retrieve, the following applies:

  1. The request must specify the profile ID, provisioning ID/code of the profile, or the unique profile ID and profile type. UniqueProfileID can only be used to retrieve. If the unique profile ID is used to retrieve, ProfileType="Traveler" is also required, as UniqueProfileID only applies to traveler profiles at this time.

    2. Note: If the provisioning code is specified, the profile type must also be specified, because the API does not control whether the provisioning code is unique across all entities, or only among entities of a given type.

  2. The request may optionally specify whether to return data from profiles that are ancestors of the requested profile.

    3. Notes:

    Response Information

    		 Profile Type

    Attribute Settings in Request

    No data about parents

    		 Any

    ReturnParent=False

    ReturnParentSummary=False

    Summary data about parents, including basic information about the parent plus all ancestors to root

    		 Any

    ReturnParent=False

    ReturnParentSummary=True

    Inherited data about parents, including basic information about each ancestor and any ancestor data that is inheritable

    		 Any

    ReturnParent=True

    ReturnParentSummary=False

    Inherited data about parents, including basic information about each ancestor and any ancestor data that is inheritable, up to root level

    Traveler, Traveler Group, or Account

    Agency, Branch Group, Branch, or Agent

    ReturnParent=True

    FullParentHierarchy=True
    Inherited data, up to account level Traveler or Traveler Group

    ReturnParent=True

    FullParentHierarchy=False

    Account data only. Warning is returned: "Account is the highest level in the restricted hierarchy, hence no parent data is returned."

    		 Account

    ReturnParent=True

    FullParentHierarchy=False

    Warning is returned: "Hierarchy can be restricted only if Inherited Data has been requested."

    		 Traveler, Traveler Group, or Account

    ReturnParent=False

    FullParentHierarchy=False (ignored)

    Summary data about parents, including basic information about the parent plus all ancestors to root

    		 Traveler, Traveler Group, or Account

    ReturnParent=False

    FullParentHierarchy=True
    Warning is returned: "Hierarchy can be restricted only for profile types Traveler, Traveler Group, or Account." Agency Group, Agency, Branch Group, Branch, or Agent

    ReturnParent=True

    FullParentHierarchy=False (ignored)

    Warning is returned: "Hierarchy can be restricted only for profile types Traveler, Traveler Group, or Account."

    		 Agency Group, Agency, Branch Group, Branch, or Agent

    ReturnParent=False

    FullParentHierarchy=False (ignored)

    Summary data about parents, including basic information about the parent plus all ancestors to root

    		 Agency Group, Agency, Branch Group, Branch, or Agent

    ReturnParent=False

    FullParentHierarchy=True

  3. The request may optionally specify the ID of the profile’s immediate parent (specifically for the case of travelers, which can have multiple immediate parents). If provided, the service will use this parent to crawl up the profile hierarchy and identify the correct ancestors to return.
  4. If the user has appropriate security resources, the user can request that masked data be unmasked. The default response masks data unless the request specifies otherwise.
    Note:     The unmask flag applies only to the profile being retrieved, not to data from parent profiles that might be included in the response. Specifically, this means that if a parent profile has inheritable data that is masked, retrieving the child profile (with inherited data from parent profiles) could show the child data unmasked, but parent data will always be masked. The user has to retrieve the parent profile (with the appropriate resources and flag to request data unmasked) to get the parent data unmasked.

With the profile retrieve request, the ProfileDataFilter can be used filter the response so that only specified data is returned. The ProfileDataCategory is used filter the retrieve response so that only the data in the specified categories are returned. Optionally, the GeoPoliticalAreaFilter can also be used in conjunction with the ProfileDataCategory to only retrieve parts of a profile by geographic location within the specified categories.

The ProfileDataCategory element is used to specify one or more categories of data (e.g., only air preferences) to return. If no category is specified, then the default category (i.e., general information) will be used by default.
Note: The categories available are an enumerated list defined in the schema. The client application cannot define or manage the list of categories supported.

Enumeration Description

General Information

Basic information (AgencyInfo/BranchGroupInfo/etc) and AccountingReference for Traveler

All Details

All stored profile data

Alternate Contacts

Basic information and all AlternateContact data for the retrieved profile including:

  • Address
  • Phone
  • ElectronicAddress

Custom Information

All data for all custom fields/field groups and basic information

Commissions

Commission data for the retrieved profile and basic information

Contracts

Contract data for the retrieved profile and basic information

Forms of Payment

Payment data for the retrieved profile and basic information

Loyalty Programs - All

All loyalty program enrollment data for each SupplierType and basic information

Loyalty Programs - Air

All loyalty program enrollment for the Air supplier type (i.e., LoyaltyProgramEnrollment.Supplier Type=Air) and basic information enumeration Loyalty Programs - Vehicle documentation

Loyalty Programs - Vehicle

All loyalty program enrollment for the Vehicle supplier type (i.e., LoyaltyProgramEnrollment.Supplier Type=Vehicle) and basic information

Loyalty Programs - Hotel

All loyalty program enrollment for the Hotel supplier type (i.e., LoyaltyProgramEnrollment.Supplier Type=Hotel) and basic information

Loyalty Programs - Rail

All loyalty program enrollment for the Rail supplier type (i.e., LoyaltyProgramEnrollment.Supplier Type=Rail) and basic information

Loyalty Programs - Other

All loyalty program enrollment for the Other supplier type (i.e., LoyaltyProgramEnrollment.Supplier Type=Other) and basic information

PolicyReference

All Policy Reference data. Policy Reference data may display in certain responses.

Preferences - All

All preference data for each preference type (i.e., Air, Vehicle, Hotel, Rail, Other) and basic information

Preferences - Air

All Air Preference data and basic information

Preferences - Vehicle

All Vehicle Preference data and basic information

Preferences - Hotel

All Hotel Preference data and basic information

Preferences - Rail

All Rail Preference data and basic information

Preferences - Other

All Other Preference data and basic information

Service Fees

ServiceFee data for the retrieved profile and basic information

Travel Documents - All

All related data for each Travel Document and basic information

Travel Documents - Visas

All related data for Visa (i.e., TravelDocument.Type=Visa) and basic information

Travel Documents - Passports

All related data for Passport (i.e., TravelDocument.Type=Passport) and basic information

Travel Documents - Other

All related data for any travel document other than Passport or Visa (i.e., TravelDocument.Type not equal to Passport or Visa) and basic information

Traveler Links

All the links for all the profiles who are related to the requested Traveler profile and basic information

TravelerIdentityInformation

All data for all traveler identity information

The GeoPoliticalAreaFilter can be used to retrieve parts of a profile by a geographic location for the specified data category.

  • Geographic location is only applicable to the following categories: All Preferences, Air Preference, Vehicle Preference, Hotel Preference, Rail Preference, and Other Preference.
    Note: All Preferences includes air, vehicle, hotel, rail, and other.

  • This modifier returns data for the geographic location, plus data for areas that are included in the geographic area (e.g., "Paris" returns preferences for Paris; plus France, Europe, and World (above); plus CDG and ORY).

  • FilterType is a required attribute that defines how the filters is applied: Arrival, Departure, Connection, Other.

  • Departure can be used for Air, Rail, Hotel, and Vehicle preferences.

  • Arrival can be used for Air and Rail preferences.

  • Connection can be used for Air and Rail preferences.

  • Other is only applicable for Advisory and Other preferences.

The examples provided below are for illustration only and do not include all necessary XML attributes.

Desired Response

Filters Applied

Comments

Rail preferences with departures from London

ProfileDataCategory = Preferences - Rail

GeoPoliticalAreaFilter

  • FilterType = Departure

  • GeoPoliticalAreaType = City

  • GeoPoliticalAreaCode = London

For the given profile, all rail preferences that depart from London are returned. Rail preferences for geographic areas that contain London (i.e., Britain, Europe, World) are also returned.

Hotel preferences in Japan

ProfileDataCategory = Preferences - Hotel

GeoPoliticalAreaFilter

  • FilterType = Arrival

  • GeoPoliticalAreaType = Country

  • GeoPoliticalAreaCode = Japan

For the given profile, all hotel preferences for Japan are returned. Hotel preferences for geographic areas that contain Japan (i.e., Asia and World) are also returned.

Universal API considers the work area branch to be an agent’s parent when the user is emulating. Although agents are children of control branches, profile retrieve for purposes of login and most agent transactions needs to consider the work area branch as the parent.

  • If the requester is emulating (if TargetBranch in BaseReq is not null), then the API returns the profile in the context of the emulation. That is, the service treats and returns the specified (work area) branch as the agent’s parent, for purposes of returning parent summary or parent inherited information.

  • If the requester is not emulating (if TargetBranch in BaseReq is null), then the API will return the profile in its literal parent context. That is, the service will treat and return the control branch as the parent. The API will require separate security authorization to be able to retrieve in a not-emulated context.

  • Note that for traveler/account type retrieve, it is assumed that the parent is ALWAYS a work area, never a control branch. The GUI will not permit parent associations of non-agent profiles to be to a control branch.

Response

The ProfileRetrieveRsp is returned.

The amount of information in the response is dependent on the criteria submitted in the request.

If the user requests the entire profile, then the response will return all stored profile data about the requested profile. This will include at least:

  • The profile ID, Type, Status, Version.

  • The Template ID and the Template Version.

    • Note: Universal API will return the “right” template that is currently applicable. This could be the default template if no override exists or if the override is inactive; else it is the override template.

  • Preferences, contacts, travel documents, advisories, and any other party or profile data stored for that profile.

  • Any tags associated to profile data.

  • Information about any profiles linked to the profile, in the case of Traveler.

    • Note: The information returned will be the same information in the profile create/modify messaging: the ID, GivenName, Surname, and Relationship of each link. In other words, the linked profiles themselves (with all their data) are never returned.

  • The Description, if one exists.
  • The AlternateAgentID, if one exists.

Profile

The ProfileLink element returns information about the traveler to which this profile is linked. The name and email address information are populated with information provided in the linked traveler's profile. The linked traveler's email address is returned in the ElectronicAddress, if the linked traveler's profile contains an email address. If the linked traveler's profile contains more than one email address, the email with a priority order of 1 is returned; if no priority is assigned, the first email address is returned.

For retrieve (including history) responses, if the profile is being retrieved with an older version of the schema the ProfileLink element is removed and an error message is returned: Data exists. Please update to the latest schema to retrieve all data.

The PolicyReference element returns information about the traveler's corporate policy. It may include:

  • Type: HRG Policy Group, Traversa Policy Group, Employee Grade
  • Value
  • Description
  • Controlling Policy ID
  • Priority Order
  • Policy Key (uAPI Key)

If the user requests one or more categories of data, then the response will exclude any profile data not associated to one of the specified categories.

Associated tags on the data will still be returned for each data in the response.

If the user requests only summary data about each ancestor, to the root ancestor, the following data is returned for each ancestor:

  • Profile ID

  • Profile Type

  • Provisioning ID/code (if applicable)

  • Profile Version

  • Profile Name

    • Note: Agents and travelers cannot be parents to other profiles, so there is no need to deal with any Name values that are not a single field.

If the user requests inherited and summary data about each ancestor, the following data is returned for each ancestor:

  • Profile ID

  • Profile Type

  • Provisioning ID/code (if applicable)

  • Profile Version

  • Profile Name

    • Note: Agents and travelers cannot be parents to other profiles, so there is no need to deal with any Name values that are not a single field.

  • Profile Status

  • Template ID

  • Template Version

  • Note: The API will return the “right” template ID/version that is currently applicable. This could be the default template if no override exists or if the override is inactive; else it’s the override template.

  • Hierarchy Level ID

  • Data for any/all fields that was marked Inheritable in the template (or custom fields) for the ancestor.

In the case of a profile having multiple immediate parents, if the user requests to retrieve parent information (either summary or inherited) but does not specify which parent context to retrieve, then the API will return summary data only about each of the profile’s immediate parents, to enable the user to identify which parent context is appropriate. (The user can then re-send the retrieve request with the correct parent ID/context.) 

The following data will be returned for each immediate parent, about the immediate parent:

  • Profile ID

  • Profile Type

  • Provisioning ID/code (if applicable)

  • Profile Version

  • Profile Name

    • Note: Agents and travelers cannot be parents to other profiles, so there is no need to deal with any Name values that are not a single field.

The following data will be returned (for each immediate parent) about the next anchor point ancestor (i.e., about the account, if the immediate parent is a traveler group; about the agency, if the immediate parent is a branch group). This information is returned in order to allow the user to differentiate between immediate parents of the same profile Type, which could potentially have the same Name. 

  • Profile ID

  • Profile Type

  • Profile Name

The Type attribute of Address includes Work and Home enumeration values.

OtherStateProvince may be included in the response in Address, AlternateContactAddress, PaymentAddress, or TravelDocumentAddress. Note the following:

  • State and OtherStateProvince are mutually exclusive, and only one can exist in the database.
  • When OtherStateProvince is stored using the uProfile v8.0 and greater schema versions, OtherStateProvince is not returned in a response that uses an old schema.
  • If State data is passed using an older schema version, Universal API overrides OtherStateProvince if it is present.