searchPerson

Description
This transaction searches for a person party given a set of search criteria. A filter may be used with this transaction.
Web Services
Operation name: searchPerson
Service name: PartyService
Example
Find a person party that uses the family name Troop and has the birth date January 6, 1981.
Usage information
Based on the search criteria provided, the search is performed using a specific search strategy and execution path. The search is executed based on the priority of the set of valid search criteria provided using one of the strategies:
  • ID search
  • Address search
  • Contact method search
  • Name search
  • Date of birth search
  • AdminPartyId, an administration system primary key search
See the tables in the Transaction Behavior description for complete details.

This transaction supports the Pagination feature.

Preconditions
Not applicable
Mandatory input
  • LastName or
  • Address or
  • IdentificationType and IdentificationNum or
  • ContactMethodReferenceNumber and ContactMethodType or
  • DateOfBirth or
  • AdminPartyId
Inquiry levels
The search results returned in a search contain the basic details of each party found. There may be times when additional details are required. To facilitate this, the search transaction supports an InquiryLevelSource, InquiryLevelType, and InquiryLevel.

An InquiryLevelSource dictates whether search result details are returned using product-defined behavior or an external rule. Valid values for InquiryLevelSource are:

  • 0 or null – returns basic search results. InquiryLevelType and InquiryLevel are not applicable.
  • 1 – returns additional party details based on product-defined behavior according to the values of InquiryLevelType and InquiryLevel.
  • 2 – returns additional party details based on an externally defined inquiry (such as External Rule 9 – Search Party), according to the values of InquiryLevelType and InquiryLevel.

An InquiryLevelType describes what type of additional detail to retrieve and is coupled with an inquiry level and secondary inquiry level. InquiryLevelType is applicable only when the InquiryLevelSource value is 1 or 2. Valid values for InquiryLevelType are:

  • 0 or null – returns basic search results. Any InquiryLevel provided will be ignored.
  • 1 – If InquiryLevelSource is 1 (product-defined behavior), this returns additional party details based on the InquiryLevel value. If InquiryLevelSource is 2 (external rule driven inquiry), this returns additional party details as determined by the external rule and the provided inquiry levels.

An InquiryLevel is associated with an InquiryLevelType and determines the level of additional detail to be returned. The transaction can include up to two separate inquiry levels: InquiryLevel and SecondaryInquiryLevel.

  • When InquiryLevelSource is 1 (product-defined behavior) and InquiryLevelType is 1, the InquiryLevel corresponds to the same party inquiry levels used in the getPerson transaction. If it is not set in the request, the default value of 0 is used. In this case, the SecondaryInquiryLevel is not used.
  • When InquiryLevelSource is 2 (external rule driven inquiry) and InquiryLevelType is 1, the inquiry levels are dependent on External Rule 9 for search party. With the default rule, InquiryLevel is used as the contract inquiry level. In this case, a default value of 1 is used if not set in the request, since the getAllContractsByParty transaction requires an inquiry level of 1 or higher. SecondaryInquiryLevel is used as the party inquiry level. If not set in the request, the SecondaryInquiryLevel uses the default value of 0.
Note: For details on party inquiry levels and contract inquiry levels, see the getPerson, getOrganization and getContract transaction documentation.
Filter values
A filter value can be supplied. Valid values are:
  • ACTIVE – returns only active person records, including active child objects according to the inquiry level.
  • INACTIVE – returns only inactive person records, including active child objects according to the inquiry level.
  • ALL – returns all records matching the search criteria, both active and inactive. Only active child objects are returned.

If the filter value is not supplied, then all records are returned.

Filter values are case-sensitive and must be provided in upper case.

The filter value is applied to the set of person parties resulting from the search, but is not applied to any child object criteria used in the search.

Wildcards
You can perform searches using partial search criteria that include the wildcard character, which is a percent sign (%).
In most cases, wildcard searches can be executed by entering one or more percent signs anywhere within the search criteria. For example, to search for every person party in the database whose family name begins with "Smit", set the family name in the transaction to "Smit%".
Wildcards can be used anywhere within a field, in the beginning, end or middle. For example, "%mith", "smit%" and "sm%th%" are all supported.
For lists of fields that support wildcard characters, see the following tables:
Restriction: Wildcard characters generally cannot be used in numeric or timestamp fields. See the Transaction Behavior section for exceptions.
Look-alikes
You can perform searches using partial search criteria that include the look-alike character, which is a question mark (?).
Look-alike searches can be executed by entering one or more question mark signs anywhere within the search criteria. For example, a family name search for "Sm?th" returns all parties where the family name is Smith, Smath, Smuth, Smoth, and others. Look-alikes can be used anywhere within a field, in the beginning, end or middle. For example, "?mith", "smit?" and "sm?th" are all supported.
For lists of fields that support wildcard characters, see the following tables:
Restriction: Look-alike characters generally cannot be used in numeric or timestamp fields. See the Transaction Behavior section for exceptions.
Phonetic search
You may wish to search for a party using a phonetic, or sounds like, search. You can use a phonetic search to look for an organization name, family name, given name, or city. For example, you may search for the person ‘Stephen Leighton' using search criteria of ‘Steven Layton'.
The results of a phonetic search include both exact and phonetic matches. The score for a phonetic match would be the exact match score multiplied by a phonetic weighting factor, for example, 75%. If name standardization is turned on, the search criteria are matched phonetically with the standardized name. Phonetic search is supported for a range of Latin-based languages, specifically, Western European languages, Eastern European Languages, and Slavic Languages. Phonetic search is not supported on search criteria containing wildcard or look-alike characters.
Common Name Exclusions
Common Name Exclusion search provides the ability to provide search criteria exclusions, for example, common family names, when searching for persons. With this feature, long-running queries and searches that yield large, meaningless results sets can be prevented. Specifically, searches based on the following exclusion rules can be prohibited:
  • Common family names
  • Common family names with given names
  • Common family names in selected cities
Common names are names that occur within the InfoSphere MDM database more than a specified number of times, for example more than 1,000 times. In addition, phonetic variations and standardized names are also taken into consideration when forming the exclusion rules.
Party macro role search
You can search for a party within the context of its party macro role. When searching for a party by macro role, the party macro role must match the macro role search criteria. For each search criterion provided, a corresponding party macro role association, for example, the name, address, contact method, identifier, party equivalency, for that party macro role must exist; if they do not exist the search will fail.
Search results
The maximum number of parties returned in the transaction response is configurable in the Configuration and Management component. It is also possible to set the maximum number of parties returned within the transaction itself. However, if this number is higher than that set in the Configuration and Management component, the number of parties returned in the response is set to the Configuration and Management component limit. For example, if there are 200 person parties in the database with the family name 'Smith' and the maximum search results returned on the Configuration and Management component is set to 100, then a family name search for Smith will return only 100 parties.

The search results are scored based on matching search criteria, and the search results list is then sorted by descending score.

When searching by party equivalency, the search results may include both person and organization business objects.

The following search configuration items control the types of address, name, and party identification that are used in the search. For all matched records, the entire set of party data is returned.
  • /IBM/Party/Search/ReturnValue/personIdentificationType
  • /IBM/Party/Search/ReturnValue/personNameUsageType
  • /IBM/Party/Search/ReturnValue/personAddressUsageType

For the first name usage type listed for personNameUsageType, the transaction returns both active and inactive names for that type. The transaction returns only active values for the other name usage types, address, contact number, and party identification.

For example, if the search return value for addresses (/IBM/Party/Search/ReturnValue/personAddressUsageType) is set to 1, then the first active address found with a usage type of 1 is returned in the search results. If the address with a usage type of 1 is inactive, then the transaction returns all active addresses associated with the party instead. If there is no active address, then no address is returned.

Additionally, if the configured return usage type is not available for a particular party, then the first available value returned by the database will be returned in the summary details. In this case, the returned values depend on the order of the values returned by the database.

Note: For more information about party search configuration items, see Configuring and customizing Party Search features.
Transaction behavior
Based on the search criteria provided, the search is performed using a specific search strategy and execution path. The search is executed based on the priority of the set of valid search criteria as defined in the following table:
Table 1. Search criteria priority
Path Search criteria provided Search by strategy
1 IdentificationType and IdentificationNum Identification
2 AdminPartyID Party Equivalency
3 LastName + Full Address (AddrLineOne, CityName, ZipPostalCode, ProvStateType, CountryType) Person Name
4 Full Address (AddrLineOne, CityName, ZipPostalCode, ProvStateType, CountryType) Address
5 CityName + ZipPostalCode + ProvStateType Address
6 ContactMethodReferenceNumber and ContactMethodType Contact Method
7 LastName Person Name
8 DateOfBirth, with no wildcards or look-alikes Date of Birth
The following table specifies the details associated with the Party and Contract Combined search strategy:
  • M/O = Mandatory/Optional
  • S13n = Standardization
  • Y/N = Yes/No
Table 2. Name search strategy
Field M/O Wildcards Look-alikes S13n Phonetics
LastName M Y (multiple) Y (multiple) Y Y
GivenNameOne O Y (multiple) Y (multiple) Y Y
GivenNameTwo O N N Y Y
GivenNameThree O N N Y Y
GivenNameFour O N N Y Y
DateOfBirth O Y (multiple) Y (multiple) N N
AddrLineOne O Y (multiple) Y (multiple) Y N
AddrLineTwo O Y (multiple) Y (multiple) Y N
AddrLineThree O Y (multiple) Y (multiple) Y N
CityName O Y (multiple) Y (multiple) Y Y
ZipPostalCode O Y (multiple) Y (multiple) Y N
ProvStateType O N N Y N
CountryType O N N Y N

Notes about this search strategy:

  • Multiple wildcards are supported anywhere in a field.
  • LastName and GivenNameOne are not standardized if they contain wildcard or look-alike characters.
  • No more than two of the three of the DateOfBirth components, either year, month, or day, may use a wildcard or look-alike character.
  • If the year, month or day has a wildcard or look-alike character, then the entire component becomes a look-alike character. For example, "198?-12-01" becomes "????-12-01" and "1954-%-%" becomes "1954-??-??".
  • Address is not standardized if ZipPostalCode has a wildcard or look-alike character in it.
Table 3. Identification search strategy
Field M/O Wildcards Look-alikes S13n Phonetics
IdentificationType and IdentificationNum M Y (multiple) Y (multiple) N N
LastName O Y (multiple) Y (multiple) Y N

Notes about this search strategy:

  • Multiple wildcards are supported anywhere in the field.
  • If the identification does not have a wildcard or a look-alike character at the end of the field, then LastName is optional.
  • If the identification does not have a wildcard or look-alike character, then LastName is ignored.
Table 4. Address search strategy
Field M/O Wildcards Look-alikes S13n Phonetics
AddrLineOne O N N Y N
AddrLineTwo O N N Y N
AddrLineThree O N N Y N
CityName M N N Y Y
ZipPostalCode M Y (multiple) Y (multiple) Y N
ProvStateType M N N Y N
CountryType O N N Y N

Notes about this search strategy:

  • The address is standardized unless ZipPostalCode has a wildcard or look-alike character in it.
  • Multiple wildcards are supported anywhere in the ZipPostalCode field.
Table 5. AdminPartyID search strategy
Field M/O Wildcards Look-alikes S13n Phonetics
AdminPartyID M Y (multiple) Y (multiple) N N
AdminSystemType O N N N N

Notes about this search strategy:

  • Multiple wildcards and look-alikes are supported anywhere in the AdminPartyID field, when partial data is known.
Table 6. Date of birth search strategy
Field M/O Wildcards Look-alikes S13n Phonetics
DateOfBirth M N N N N
Table 7. Contact method search strategy
Field M/O Wildcards Look-alikes S13n Phonetics
ContactMethodReferenceNumber and ContactMethodType M Y (multiple) Y (multiple) Y N
LastName O Y (multiple) Y (multiple) Y N

Notes about this search strategy:

  • Multiple wildcards are supported anywhere in the field.
  • If the ContactMethodReferenceNumber does not have a wildcard or a look-alike character at the end of the field, then LastName is optional.
  • ContactMethodReferenceNumber is not standardized if it includes a wildcard or look-alike character.

The filter value is applied to the set of Person parties resulting from the search, but the filter is not applied to any of the child object criteria used in the search.

If the filter value is not provided, the transaction retrieves all active and inactive party records.

If the filter value is misspelled, the transaction fails and returns an error message.

If phonetic search is configured on, then the search result set includes both exact and phonetic matches.

If search exclusions is configured on, and if the search criteria match those found in the common name exclusion set, for example, the criteria matches a common family name; a family name and given name one pair; or family name and city pair, or represents an even broader search when wildcard or look-alikes are used, then the search does not execute and the transaction fails.

Request message
<TCRMTxType> SearchPerson

<TCRMTxObject> TCRMPersonSearchBObj

<TCRMObject> TCRMPersonSearchBObj

Response objects
TCRMPersonSearchResultBObj object
Note: If ZipPostalCode is part of the search criteria (searchyPersonByAddress), then the search result TCRMPersonSearchResultBObj does not contain attributes such as GivenNameOne, GivenNameTwo, LastName, and IdentificationTypeValue. However, if ZipPostalCode is not part of the search criteria (searchPersonByName), then the search result TCRMPersonSearchResultBObj does contain the previously mentioned attributes.
Special note
Not applicable