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
- 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 ofMatch
. - A value of
3
indicates a probabilistic match threshold type ofPossible Match
. - A value of
4
indicates a probabilistic match threshold type ofNo Match
.
- A value of
- 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.IdentificationNumberNote: 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
- 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
- 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
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:
- TCRMPersonBObj
- TCRMPersonNameBObj
- TCRMPartyAddressBObj, each containing TCRMAddressBObj
- TCRMPartyContactMethodBObj, each containing TCRMContactMethodBObj
- TCRMPartyIdentificationBObj
- TCRMPartyBankAccountBObj
- TCRMPartyChargeCardBObj
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