PairMatchRequest

The PairMatchRequest is a synchronous SOAP web service request in XML format your application sends to Verato Auto-Steward. It is available as

• The request contains two identity objects that suspected to be the same person.
• The response contains the result for the pair match decision along with supporting evidence to justify the result. The supporting evidence includes the matching Verato reference identity, if one was found, along with metadata about the similarity between the input identities and the Verato reference identities.

PairMatchRequest elements

• RequestId — A string that clients can use to provide a unique ID or string of information to track each web service request. The RequestId should uniquely identify each web service request. The RequestId is returned in the web service response to associate the response to the request. Many Verato clients use the RequestId as a mechanism to associate each web service request back to the data stewardship tasks in their MPI/MDM system.
• Identity1 — This element is made up of the personally identifiable information (PII) for the first of the two input identities.
• Identity2 — This element is made up of the PII for the second of the two input identities.

PairMatchRequest — Identity elements

The elements within the Identity data type are as follows:

• PersonName — The name for the identity
  • Prefix (string)
  • First (string)
  • Middle (string)
  • Last (string)
  • Suffix (string)
• Credentials — The SSN credentials for the identity
  • SSN (string of 9 digits, numbers only)
• BirthDetails — The DOB for the identity
  • Date (type=date, YYYY-MM-DD format)
• PhysicalDescription — The Gender code for the identity
  • Gender (single-digit gender code, such as M or F)
• SimpleAddress — The address for the identity, in basic street line 1/line 2 format (which is the format most commonly used)
  • Line1 (string)
  • Line2 (string)
  • City (string)
  • State (2-character code)
  • ZipCode (5-digit number)
  • ZipCodePlusFour (4-digit number)
• DetailedAddress — The address for the identity in a more fine-grained format, where each address line is already parsed into components such as house number, street name, street type, and so This variation of address is rarely used since most clients do not have address data already parsed to this level of granularity.
  • HouseNumber (string)
  • StreetDirection (string with abbreviated direction, such as E, N, SE, SW, )
  • StreetName (string)
  • StreetType (string)
  • StreetPostDirection (string with abbreviated direction, such as E, N, SE, SW, )
  • UnitType (string)
  • UnitNumber (string)
  • City (string)
  • State (2-character code)
  • ZipCode (5-digit number)
  • ZipCodePlusFour (4-digit number)
• ContactPhone — The phone number for the identity
• PhoneCountryCode (string)
• PhoneAreaCode (string)
• PhoneBaseNumber (string)
• PhoneExtension (string)
• ContactEmail — The email address for the identity
  • Email (string)

PairMatchResponse elements

The PairMatchResponse is the web service response in XML format that Verato provides your application in answer to a PairMatchRequest. The body of the web service response XML contains an element called PairMatchResponse .

ThePairMatchResponse element is made up of several sub-elements:

• RequestId — The RequestId from the web service request is echoed back here
• MatchResult — The outcome for the pair match decision. Was the pair of input identities deemed to be the same person or not?
• Identity1CommercialMatches — If a close match was found in Verato’s Reference Database for the 1st input identity, that Reference Database identity is returned here to show how the reference identity's attribute data is similar to the input identity. If a close match was not found in Verato’s Reference Database for the 1st input identity, then this element is empty.
• Identity2CommercialMatches — if a close match was found in Verato’s Reference Database for the 2nd input identity, that Reference Database identity is returned here to illustrate how the reference identity is made up of attribute data that is similar to the input identity. If a close match was not found in Verato’s Reference Database for the 2nd input identity, this element is empty.
• Identity1AttributeMatchTable — this element contains the match codes for each attribute for the 1st input identity compared to the Identity1CommercialMatch (if a close match was found). The match codes represent the degree of similarity between each attribute of the 1st input identity and the Identity1CommercialMatch from Verato’s Reference Database.
• Identity2AttributeMatchTable — this element contains the match codes for each attribute for the 2nd input identity compared to the Identity2CommercialMatch (if a close match was found). The match codes represent the degree of similarity between each attribute of the 2nd input identity and the Identity2CommercialMatch from Verato’s Reference Database.
• PairAttributeMatchTable —  The Auto-Steward web service compares the two input identities against each other independent of their respective matches from Verato’s Reference Database. The PairAttributeMatchTable element contains the match codes from this comparison and shows the degree of similarity between each attribute for input identity 1 versus input identity 2.
• Identity1 — An ‘echo’ back of the 1st input
• Identity2 — An ‘echo’ back of the 2nd input

PairMatchResponse - MatchResult elements

The first and most important element in the PairMatchResponse is the MatchResult element, which indicates the outcome of the Auto-Steward request. The MatchResult element contains the following sub-elements:

• SameIdentity — A Y/N/U code that represents the answer to the question, “Are my two input identities the same person or not?”. If SameIdentity =Y, then the AUTO-STEWARD service is asserting that the two input identities represent the same If SameIdentity =N, then the AUTO-STEWARD service is asserting that the two input identities represent two different people definitively. If  SameIdentity =U, then the AUTO-STEWARD service is asserting that there is still ambiguity and the two input identities are not deemed to be definitively the same or not — the outcome is Uncertain. When SameIdentity =U, this is essentially saying “your MPI/MDM was already uncertain whether these two identities are the same person, and Verato is also uncertain.” Some clients choose to take this outcome and act on it by deleting the data stewardship work item from the work queue (no sense spending any more time on it if it’s that ambiguous); other clients choose to take this outcome and assess more details from the web service response in order to decide how high or low a priority it is to have a human data steward still review the data stewardship work item.
• HeadToHeadMatch — Describes the overall SameIdentity response for the pair. If HeadToHeadMatch =true, AUTO-STEWARD based the final SameIdentity decision on a head-to-head match of the two input records. If HeadToHeadMatch =false, AUTO-STEWARD based the final SameIdentity decision on matches of the input identities to the Reference Database. Some clients opt to ignore any AUTO-STEWARD results based on a ‘head-to-head’ match, since the client already attempted to match the identities ‘head-to-head’ with their own MPI/MDM matching algorithm. For those clients, the HeadToHeadMatch element may be used to identify which AUTO- STEWARD results were based on a head-to-head comparison.
• Memo — this is a text string explaining how Verato arrived at the SameIdentity decision. For example, if each of the two inputs was a match to the same reference identity in Verato’s Reference Database, then the memo string would indicate something like this: “Identity1 and Identity2 matched the same commercial identity and therefore are the same ” Or if the inputs did not definitively match to a reference identity in Verato’s Reference Database, but they DID match to each other in a head-to-head comparison with Verato’s matching algorithm, then the memo string would indicate something like this: “Matching commercial identities were not found for Identity1 and/or Identity2. This result refers to a head-to-head match.”
• NormalizedScore — The match score, on a scale from 0.0 to 1.0, that Verato assigned to the overall pair In the event that both inputs matched to the same reference identity in Verato’s Reference Database. The NormalizedScore will be the lower of the two scores from the input identities’ matches against the Reference Database (and the score will be 0.8 or higher, since that is the threshold at which an input identity would be considered a match to a Reference Database reference identity). In the event that the input identities were compared head-to-head against each other to arrive at the answer of SameIdentity =Y, this NormalizedScore would be the score from the comparison of the two input identities against each other (and the score would be 0.8 or higher). If the SameIdentity result was U or N, there is more complicated logic that dictates what value is reported for NormalizedScore , and Verato does not recommend that clients worry about trying to interpret the NormalizedScore in these cases.

The Identity1CommercialMatches and Identity2CommercialMatches elements contain either 0 or 1 identities from Verato’s Reference Database. These represent the reference identities that were the closest match to each of the input identities — the Reference Database identities are included in the response as supporting evidence to illustrate that the reference identity was similar to the input identity.

Each input identity is compared against Verato’s Reference Database to determine if there is a matching reference identity, and then the matching algorithm assigns a score to the match.

• If a matching reference identity was found with a match score of 0.8 or higher, this is deemed to be the same identity as the input identity.
• If a matching reference identity was found with a match score of 0.7 or higher but below 0.8, this is deemed to be an uncertain match — Verato is not declaring that the reference identity is the same person as the input identity, but Verato still returns this closest-matching reference identity in the web service response in the event that it is useful to the client to see the information.
• If a matching reference identity was not found with a match score of at least 0.7, then the Identity1CommercialMatches (or Identity2CommercialMatches ) element will be empty to ensure that Verato does not unnecessarily disclose the identity information of a reference identity record that is not likely to be the same person as the input identity.

PairMatchResponse — CommercialMatch elements

The Identity1CommercialMatches and Identity2CommercialMatches elements are made up of an element called CommercialMatch. The CommercialMatch element includes a SameIdentity (Y/N/U) indicator for the individual match. (Y means the reference identity was a match to the input identity at a score of 0.8 or greater; U means the reference identity was a close-but-not-close-enough match to the input identity at a score less than 0.8 but greater than 0.7) as well as the NormalizedScore for the individual match.

The CommercialMatch element also contains the following sub-elements:

• AraxidID — The unique identifier of the reference identity record in Verato’s Reference Database.
• Enhancement — Indicates whether any enhancements were applied to the match score during the matching Enhancements can either be bonuses that increase the match score due to uniqueness of the identity or penalties that decrease the match score when certain conditions are detected that indicate a potential parent/child pattern or a twin sibling pattern. There can be zero-to-many instances of the Enhancement element.
• PersonName — Contains the same sub-elements that were described for PersonName under PairMatchRequest Elements. In addition, each sub-element includes a matchCode , which is a code indicating the degree of similarity between the input identity and the reference identity.
• Credentials — this is made up of the same sub-elements that were described for Credentials under PairMatchRequest Elements. In addition, each sub-element includes a matchCode , which is a code indicating the degree of similarity between the input identity and the reference identity.
• BirthDetails — this is made up of the same sub-elements that were described for BirthDetails under PairMatchRequest Elements. In addition, each sub-element includes a matchCode , which is a code indicating the degree of similarity between the input identity and the reference identity.
• PhysicalDescription — this is made up of the same sub-elements that were described for PhysicalDescription in section 3.1.1. In addition, each sub-element includes a matchCode , which is a code indicating the degree of similarity between the input identity and the reference.
• DetailedAddress —Contains the same sub-elements that were described for DetailedAddress
• under PairMatchRequest Elements. In addition, each sub-element includes a matchCode indicating the degree of similarity between the input identity and the reference identity.
• ContactPhone — Contains the same sub-elements that were described for ContactPhone
• under PairMatchRequest Elements. In addition, each sub-element includes a matchCode indicating the degree of similarity between the input identity and the reference identity.
• ContactEmail — Contains the same sub-elements that were described for ContactEmail
• under PairMatchRequest Elements. In addition, each sub-element includes a matchCode indicating the degree of similarity between the input identity and the reference identity.
• DeathDetails — If Verato’s reference database indicates this person is deceased, the web service response would include a DeathDetails element, which is made up of a sub-element called Date , which indicates the date-of-death for the individual.

PairMatchResponse — Identity1AttributeMatchTable

The Identity1AttributeMatchTable and Identity2AttributeMatchTable elements contain a series of match codes for each attribute used in the matching process for matches between the input identities and Verato’s Reference Database.

Each sub-element is called AttributeMatch, and contains a ‘name’ and ‘value’.

• The ‘name’ is a string that indicates the attribute in question.
• The ‘value’ is the match code indicating the degree of similarity. If the 1st or 2nd input identities did not have a corresponding match (or near-match) in the Identity1CommercialMatches or Identity2CommercialMatches , then the Identity1AttributeMatchTable (or Identity2AttributeMatchTable ) will be empty.

PairMatchResponse — PairAttributeMatchTable

The PairAttributeMatchTable element contains a series of match codes for each attribute used in the matching process when comparing the two input identities against each other.

This element will always be populated. Because the web service request always contains two input identities, there will always be a head-to-head comparison with the match codes represented in PairAttributeMatchTable.

Note that the result of the head-to-head comparison is not always used to make the final determination of whether the two identities are the same person. Typically, the result of matching each input identity against Verato’s Reference Database is used to determine if the inputs are the same person, but the match codes are still returned in any case.

One final note about the web service response — you may notice in the XSD or in the response XML itself that there are additional elements that were not described above. These may include things like ‘confidence’, ‘rawScore’, ‘Grade’, or ‘Depth’. Those elements are meaningful to internal processes within the Auto-Steward service but are not needed by clients to interpret and use the results, hence they have not been described in the documentation so that our clients can focus on the useful elements of the web service response that are documented above.