searchPersonProbabilistic

Description
This transaction conducts a probabilistic search for person party records, given a set of search criteria.

Probabilistic searches use statistical methods to determine how closely party records match the given set of search criteria. The probabilistic search engine generates match scores that consider the frequency of the occurrence of a given data value within a particular distribution. For example, in English-speaking locales, the name John Smith may contribute less to a match score than the name Frederico Defuentes because John Smith is more common.

By contrast, the classic InfoSphere® MDM deterministic search, as used by searchPerson, derives its match scores by determining if there is an exact match between the search criteria and the corresponding data in a candidate record.

Web Services
Operation name: searchPersonProbabilistic
Service name: PartyService
Example
Find a person party with the name Carl Johnson and a birth date of January 6, 1981.

Find a person party with the surname Johnson and an address postal code of 01812.

Usage information
By default, the searchPersonProbabilistic transaction leverages the same algorithm that the IBM® InfoSphere MDM Probabilistic Matching Engine uses to perform probabilistic party matching. If you want to search using a different preconfigured algorithm, you must supply the corresponding PMEContextKey.
Restriction: Probabilistic search services do not support the use of wildcard characters or look-alike characters. If wildcard or look-alike characters are included in the search criteria, the searchPersonProbabilistic transaction considers them as part of the search string. However, in probabilistic matching, partial matches do contribute to the search score by default.

In probabilistic searches, each criterion provided in the search request will contribute to the search score for each record being searched. The search results will return only records that meet a minimum search score threshold.

Tip: To improve the quality of the search results, include as many search criteria as possible.

When using the default probabilistic matching algorithm, one or more of the following search criteria can be provided:

Person
  • TCRMPersonBObj.BirthDate
Person Name
  • TCRMPersonNameBObj.NameUsageType
  • TCRMPersonNameBObj.NameUsageValue
  • TCRMPersonNameBObj.GivenNameOne
  • TCRMPersonNameBObj.GivenNameTwo
  • TCRMPersonNameBObj.LastName
Address
  • TCRMPartyAddressBObj.AddressUsageType
  • TCRMPartyAddressBObj.AddressUsageValue
  • TCRMAddressBObj.AddressLineOne
  • TCRMAddressBObj.AddressLineTwo
  • TCRMAddressBObj.City
  • TCRMAddressBObj.ResidenceNumber
  • TCRMAddressBObj.ProvinceStateType
  • TCRMAddressBObj.ProvinceStateValue
  • TCRMAddressBObj.ZipPostalCode

The AddressUsageType and AddressUsageValue are optional. However, if the address is a business address, then it is important to provide the AddressUsageType, because the probabilistic matching algorithm scores business addresses differently than it scores personal addresses.

If no AddressUsageType or AddressUsageValue are provided, the transaction treats the address as a personal address and compares it against addresses of all usage types in the InfoSphere MDM Probabilistic Matching Engine indices that do not correspond to a business address.

Party Identification
  • TCRMPartyIdentificationBObj.IdentificationType
  • TCRMPartyIdentificationBObj.IdentificationValue
  • TCRMPartyIdentificationBObj.IdentificationNumber

The search transaction considers only Social Security Number and Social Insurance Number.

The IdentificationType or IdentificationValue must be provided along with the IdentificationNumber.

Contact Method
  • TCRMPartyContactMethodBObj.ContactMethodUsageType
  • TCRMPartyContactMethodBObj.ContactMethodUsageValue
  • TCRMContactMethodBObj.ReferenceNumber
The search transaction considers only the following contact method usage types:
  • Home telephone
  • Cellular
  • Mobile telephone
  • Business telephone

The ContactMethodUsageType or ContactMethodUsageValue are optional. However, if the contact method is a business phone number, then it is important to provide the ContactMethodUsageType, because the probabilistic matching algorithm scores business phone numbers differently than it scores personal phone numbers.

If neither the ContactMethodUsageType nor the ContactMethodUsageValue are provided, the transaction treats the phone number as a personal phone number and compares it against phone numbers of all usage types in the InfoSphere MDM Probabilistic Matching Engine indices that do not correspond to a business telephone number.

The transaction request supports multiple person names, addresses, contact methods, and identifications as search criteria. In general, when multiple business objects in a search are of the same type, they are searched with an OR relationship. Business objects of different types are searched with an AND relationship. For example:

  • If two different names, Name1 and Name2, are provided as search criteria, then the search results correspond to candidates that match either Name1 or Name2.
  • If a name, Name1, and a home address, Address1, are provided as search criteria, then the search results correspond to candidates that match both Name1 and Address1.
  • If two names, Name1 and Name2, and a home address, Address1, are provided as search criteria, then the search results correspond to candidates that match either of the following:
    • Name1 and Address1
    • Name2 and Address1

Other party data that are included in a search request but are not identified as a matching data element in the probabilistic matching algorithm will be ignored by the transaction.

To override configuration defaults, you can provide the following additional parameters in the search request:

MaxReturn
The maximum number of party records that the transaction will return.

By default, the maximum number of party records returned in the transaction response is configurable in the Configuration and Management component. However, you can use the MaxReturn parameter in the transaction request to override the configured default maximum.

Restriction: You can only use MaxReturn to set the maximum number of returned parties to be less than the configured value, not larger. If the MaxReturn value is higher than the configured value, then the number of parties returned in the response will be set to the configured maximum value.
MinSuspectType
The minimum suspect type threshold for which matched records will be returned.

This value can be provided to override the default suspect type of a B match (a possible match). Valid values for MinSuspectType are defined in the CDSUSPECTTP code table:

  • A value of 1 indicates a probabilistic match threshold type of Match.
  • A value of 3 indicates a probabilistic match threshold type of Possible Match.
  • A value of 4 indicates a probabilistic match threshold type of No Match.
MinScore
The minimum score for which matched parties will be returned. This numeric value can be provided to override the default setting of a possible match (a B match). If the MinSuspectType is also provided in the request, then the transaction will use the MinSuspectType value instead of the MinScore value.

This transaction supports the Pagination feature.

Preconditions
  • The InfoSphere MDM Probabilistic Matching Engine must be configured.
  • Party matching data must be synchronized with the InfoSphere MDM Probabilistic Matching Engine indices.
Mandatory input
One or more of the following search criteria must be provided in the search request:
  • TCRMPersonBObj.BirthDate
  • TCRMPersonNameBObj.GivenNameOne
  • TCRMPersonNameBObj.GivenNameTwo
  • TCRMPersonNameBObj.LastName
  • TCRMAddressBObj.AddressLineOne
  • TCRMAddressBObj.AddressLineTwo
  • TCRMAddressBObj.City
  • TCRMAddressBObj.ResidenceNumber
  • TCRMAddressBObj.ProvinceStateType
  • TCRMAddressBObj.ProvinceStateValue
  • TCRMAddressBObj.ZipPostalCode
  • TCRMContactMethodBObj.ReferenceNumber
  • TCRMPartyIdentificationBObj.IdentificationNumber
    Note: If the TCRMPartyIdentificationBObj.IdentificationNumber is provided, you must also include one of the following:
    • TCRMPartyIdentificationBObj.IdentificationType
    • TCRMPartyIdentificationBObj.IdentificationValue
Inquiry levels
Not applicable
Filter values
Not applicable
Transaction behavior
The InfoSphere MDM Probabilistic Matching Engine compares the search criteria that you provide to matching data for Person records in the InfoSphere MDM Probabilistic Matching Engine indices.

The search transaction uses the search criteria to identify a list of candidates through the InfoSphere MDM Probabilistic Matching Engine bucketing strategy. There are several default search buckets configured.

Name
There is an exact match on any two of the following:
  • Given name one
  • Given name two
  • Surname
Nicknames, as defined in the InfoSphere MDM Probabilistic Matching Engine configuration, are considered. Phonetic values are not considered.
Name and Birth date
There is an exact match on the birth date and, for name, any one of the following:
  • Given name one
  • Given name two
  • Surname
Both InfoSphere MDM Probabilistic Matching Engine-defined nicknames and phonetic values are considered.
Name and ZIP/postal code
There is an exact match on the ZIP or postal code and, for name, any one of the following:
  • Given name one
  • Given name two
  • Surname
Both InfoSphere MDM Probabilistic Matching Engine-defined nicknames and phonetic values are considered.
Note: All addresses except business addresses are considered in the Name and ZIP/postal code bucket.
Phone number
There is an exact match on a phone number type of contact method (other than business telephone).
Business telephone
There is an exact match on a business telephone type of contact method.
Social Security Number
There is an exact match on a Social Security Number type of identification number.
Social Insurance Number
There is an exact match on a Social Insurance Number type of identification number.

After all candidates have been identified using the bucketing strategy, each candidate party is compared against all of the search criteria and assigned a search score that represents how closely the candidate matches the search criteria. The search transaction only returns records that have a score higher than a given search threshold.

The InfoSphere MDM Probabilistic Matching Engine indices capture matching data for active parties only so, in general, the transaction can only return parties that are active.

For the matched records returned by the search, the types of party data returned for address, name, and party identification are governed by default search configurations. The transaction returns inactive names only if no active names are available. However, only active values for address, contact number, and party identification are returned.

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 the next available active address associated with the party instead. If there is no active address, then no address is returned.

Note: For more information about configuring defaults for probabilistic searches, see Configuring probabilistic party searches.
Request message
<TCRMTxType> SearchPersonProbabilistic

<TCRMTxObject> ProbabilisticPersonSearchBObj

<TCRMObject> ProbabilisticPersonSearchBObj

with one or more business objects:

Restriction: A maximum of one TCRMPersonBObj is allowed in each request.
Attention: TCRMPersonNameBObj, TCRMPartyAddressBObj, TCRMPartyContactMethodBObj, TCRMPartyIdentificationBObj, TCRMPartyBankAccountBObj and TCRMPartyChargeCardBObj should be provided at the same level as TCRMPersonBObj. If they are embedded as child objects in TCRMPersonBObj, they will be ignored.
Note: TCRMPartyBankAccountBObj and TCRMPartyChargeCardBObj can be used as search criteria if bank accounts and charge cards are configured in the InfoSphere MDM Probabilistic Matching Engine matching algorithm. However, the default InfoSphere MDM Probabilistic Matching Engine algorithm does not include bank accounts and charge cards.
Response objects
One or more ProbabilisticPersonSearchResultBObj objects, each containing TCRMPersonSearchResultBObj
Special note
Not applicable