searchParty
- Description
- This transaction searches for a party given a set of search criteria. A filter may be used with this transaction.
- Web Services
- Operation name: searchParty
- Service name: PartyService
- Example
- Find the party that uses the name AlphaGroup.
- Usage information
- The party type must be provided in the transaction if AdminPartyId,
the administration system primary key, is not used as a search criterion.
If the AdminPartyId is used, the party type does not need to be provided.
The function of this transaction is identical to the searchPerson and searchOrganization transactions for the respective party types. See the searchPerson and searchOrganization transactions for additional usage information details.
This transaction supports the Pagination feature.
- Preconditions
- Not applicable
- Mandatory input
- LastName or
- OrganizationName or
- Address or
- IdentificationType and IdentificationNum or
- ContactMethodReferenceNumber and ContactMethodType or
- EstablishedDate 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 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, 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 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. For example, "%mith%", "smit%" and "sm%th%" are all
supported.
For lists of fields that support wildcard characters, see either searchOrganization (for organization parties) or searchPerson (for person parties).
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 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 lists of fields that support look-alike characters, see either searchOrganization (for organization parties) or searchPerson (for person parties).
- 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.
- Common Name Exclusions
- Common Name Exclusion search provides the ability to provide search
criteria exclusions, for example, common last 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 last names
- Common last names with given names
- Common last names in selected cities
- 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 by Admin System Key
- You can search for a party using AdminPartyId, the external administration system primary key. Additional criteria such as the AdminSystemType and PartyType can be provided. If no PartyType is provided, the search response may contain both TCRMPersonSearchResultBObj person objects, and the TCRMOrganizationSearchResultBOb organization objects. Wildcard and look-alike characters can be used when searching by AdminPartyId, when only partial data is known.
- 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
- The behavior of this transaction is identical to the searchPerson and searchOrganization transactions for the respective party types. See those transactions for additional details.
- Request message
- <TCRMTxType> searchParty
<TCRMTxObject> TCRMPersonSearchBObj or TCRMOrganizationSearchBObj
<TCRMObject> TCRMPersonSearchBObj or TCRMOrganizationSearchBObj
- Response objects
- TCRMPersonSearchResultBObj object or TCRMOrganizationSearchResultBObj or both
- Special note
- Not applicable