searchFSParty

Description
This transaction searches a person or organization given a set of search criteria that includes both name and contract information. A filter may be used with this transaction.
Web Services
Operation name: searchFSParty
Service name: FinancialServices
Example
Find the person party with the last name Geary who owns a checking account agreement.
Usage information
At minimum, the person last name or organization name, and one contract element must be provided. See the table in the Transaction Behavior section for more usage information.

This transaction supports the Pagination feature.

Preconditions
Not applicable
Mandatory input
  • A contract element
  • LastName or OrganizationName
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 or getOrganization 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 party records, including active child objects according to the inquiry level.
  • INACTIVE – returns only inactive party 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 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: the 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 last name begins with "Smit", set the last name in the transaction to "Smit%".
Wildcards can be used anywhere within a field, in the beginning, end or middle, however some fields require a wildcard at the end. For example, "%mith%", "smit%" and "sm%th%" are all supported.

For a list of fields that support wildcard characters, see Table 1.

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: 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 last name search for "Sm?th" returns all parties where the last 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 a list of fields that support look-alike characters, see the table Table 1.

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, last 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.

For a list of fields that support phonetic searches, see the table Table 1.

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. If one or more contract elements are provided then the party macro role is ignored.
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 last name 'Smith' and the maximum search results returned on the Configuration and Management component is set to 100, then a last 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.
Transaction behavior
Based on the search criteria provided, the search is performed using the Party and Contract Combined search strategy. 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 1. Party and Contract Combined Search Strategy
Field M/O Wildcards Look-alikes S13n Phonetics
OrganizationName O Y (multiple) Y (multiple) Y Y
LastName O 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
EstablishedDate O Y (multiple) Y (multiple) N N
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 N Y (multiple) Y Y
ZipPostalCode O Y (multiple) Y (multiple) Y N
ProvStateType O N N Y N
CountryType O N N Y N
IdentificationType and IdentificationNum O Y (multiple) Y (multiple) N N
ContactMethodReferenceNumber and ContactMethodType O Y (multiple) Y (multiple) Y N
RoleType O N N N N
ContractStatusType O N N N N
LineOfBusiness O N N N N
BrandName O N N N N
ServiceProvId O N N N N
ServiceOrgName O Y (multiple) Y (multiple) N N
BusOrgUnitId O N N N N
AdminContractId O Y (multiple) Y (multiple) N N
AdminSystemType O N N N N
PartialSysAdminKeys O N N N N

Notes about the searchFSParty transaction:

  • At least LastName or OrganizationName must be provided. If a LastName or OrganizationName is not provided, but other party search criteria are provided, then the contract elements are ignored.
  • At least one contract element must be provided. If no contract element is provided then the transaction behavior is identical to searchParty.
  • Fields supporting multiple wildcards must have a wildcard at the end of the field. The exceptions are EstablishedDate, DateOfBirth, ZipPostalCode.
  • FullName is not standardized if a wildcard or look-alike character is used any position when performing phonetic search.
  • No more than two of the three EstablishedDate or 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.
  • ContactMethodReferenceNumber is not standardized if it has a wildcard or look-alike character in it.

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.

For person name searches, if search exclusions is configured ON and if the search criteria match those found in the common name exclusion set, then the search does not complete and the transaction fails. For example, if the criteria matches for any of the following attributes, then the search will not complete:
  • Common last name (party A last name is "Smith"; party B last name is "Smith").
  • Last name and given name one pair (party A last name is "Smith" and given name one is "John"; party B last name is "Smith" and given name one is "John").
  • Last name and city pair (party A last name is "Smith" and city is "Toronto"; party B last name is "Smith" and city is "Toronto").
  • A broader search match when wildcard or look-alikes are used.
Request message
<TCRMTxType> SearchFSParty

<TCRMTxObject> TCRMFSPersonSearchBObj or TCRMFSOrganizationSearchBObj

<TCRMObject> TCRMFSPersonSearchBObj or TCRMFSOrganizationSearchBObj

Response objects
TCRMPersonSearchResultBObj object or TCRMOrganizationSearchResultBObj objects
Special note
Not applicable