Match Entities

The Match Entities operation sends a batch of entities from a contributing source, applies match rules, and returns match results for each entity in the batch. This operation helps you test how match rules apply to entities coming from a source so you can see potential duplicate records and make match rule adjustments.

The entities are represented in XML format. The batch is not staged — you can use the Update Golden Records operation to stage a batch of entities.

Basic authentication

To perform this operation using Basic auth, send an HTTP POST request to:

https://<base URL>/mdm/universes/<universeID>/match

where base URL is the URL for your Hub cloud that hosts your repository.

JWT authentication

To perform this operation using JSON Web Token (JWT) auth, send an HTTP POST request to:

https://<base URL>/mdm/universes/<universeID>/match?repositoryId=<repository ID>

You must have the following MDM privileges:

• With the Advanced Security feature on your account:

  • MDM - Stewardship with the View Records Hub role entitlement for the queried repository
    or
  • MDM - Stewardship Management

• Without Advanced Security:

  • MDM - Stewardship
    or
  • MDM - View Data

Field values are masked if:

• Model fields contain masking configurations
• The request uses JWT authentication
• You do not have permission to view masked data. You can view masked data if you have the MDM Administrator or MDM Privileged Data Steward role, the MDM - Reveal Masked Data privilege, or the Reveal Masked Data entitlement.

note

You can implement requests for this operation in processes using the HTTP Client connector, as demonstrated by the sample process Hub: Match Entities, which you can install in your account from the process library in Integration.

You can also use Boomi DataHub connector's match entities operation.

Path parameters

universeID
ID of the universe

Query parameters

repositoryId
ID of the repository. Case sensitive. Required with JWT authentication only. You can obtain the repository ID from the URL after navigating to the repository in the user interface.

ambiguousMatchSampleSize
Returns a specified number of sample ambiguous matches when a match fails due to too many potential matches. The response includes matched entities, match rounds, and fuzzy scores to help diagnose and refine match rules. Information returned also involves information about the golden record for the match. If fuzzy rules are used and more than 1,000 candidates are evaluated, up to 200 samples can be returned.

Request body

In the request body, wrap the entities in a <batch> element. Specify the contributing source by its ID in the <batch> element’s src attribute. In each entity, wrap the source record ID in an <id> element.

For example, the following request body represents a batch from source SF:

<batch src="SF">
     <contact>
       <id>1</id>
       <name>bobby</name>
       <city>berwyn</city>
       <phones>
         <phone>
           <number>311 555-1234</number>
           <type>home</type>
         </phone>
         <phone>
           <number>311 555-4321</number>
           <type>mobile</type>
         </phone>
       </phones> 
       <email>bob@gmail.com</email>
       <spouse>1001</spouse>
     </contact>
     <contact>
       <id>2</id>
       <name>mike</name>
       <city>chesterbrook</city>
       <phones>
         <phone>
           <number>311 555-2345</number>
           <type>home</type>
         </phone>
         <phone>
           <number>311 555-5432</number>
           <type>mobile</type>
         </phone>
       </phones> 
       <email>mike@gmail.com</email>
       <spouse>1002</spouse>
     </contact>
</batch> 

*MDM* (exactly as shown here in uppercase with leading and trailing asterisks) is not a valid source ID because it is used to distinguish batches submitted manually in the Boomi DataHub service. If *MDM* is specified as the source ID, the response is an unknown source error.

Responses

• 200 (OK) In the response body the root element <MatchEntitiesResponse> consists of a <MatchResult> element for each batch entity. A <MatchResult> element has the following attributes:

  • matchRule — the match rule whose application resulted in a match (if there was a match).

  • status — these are the possible values:

    • SUCCESS — the request was successfully processed.

    • FAILED_TO_RUN — an internal error occurred.

    • TOO_MANY_MATCHES — there are 10 or more matching elements (1,000 or more in the case of an exact matching expression grouped with a fuzzy matching expression).

    • ALREADY_LINKED — the records and IDs are the same and the entity is already linked to an entity in the source system.

    • MATCH_REFERENCE_FAILURE — the entity matches on a reference field but the field value does not resolve to a golden record.

    • DUPLICATE - two records have the same data, but different IDs.

  The first child element in <MatchResult> is <entity>, which contains a copy of the entity as it appeared in the request body.

  For a result with status SUCCESS, <entity> is followed by a <match> element for each matching golden record not yet linked to an entity in the source system. There is also a <duplicate> element for each matching golden record already linked to an entity in the source system. In the golden record representations in <match> and <duplicate> elements, the id attribute value is the system golden record ID.

  If you apply a match rule specifying fuzzy matching, it includes the <fuzzyMatchDetails> element in the <match> or <duplicate> element for each matching golden record. The <fuzzyMatchDetails> element has these children:

  • <field> is the field containing the data used for matching.

  • <first> is the value of the field referenced first in the applied match rule. This value is either from the incoming entity or the matched golden record.

  • <second> is the value of the field referenced second in the applied match rule. This value is either from the incoming entity or the matched golden record.

  • <method> is the similarity algorithm specified by the applied match rule — either jarowinkler (Jaro-Winkler), levenshtein, bigram, trigram or soundex.

  • <matchStrength> is the strength of the fuzzy match. A value of 1.0 indicates perfect similarity.

  • <threshold> is the tolerance level for application of the similarity algorithm specified by the applied match rule.

  Field values are masked if masking is configured in the model and the user cannot view masked data.

  Sample response body:

  
  <MatchEntitiesResponse>
     <MatchResult matchRule="Incoming name is similar to (Jaro-Winkler) Existing name" status="SUCCESS">
       <entity>
         <contact>
           <id>1</id>
           <name>bobby</name>
           <city>berwyn</city>
           <phones>
             <phone>
               <number>311 555-1234</number>
               <type>home</type>
             </phone>
             <phone>
               <number>311 555-4321</number>
               <type>mobile</type>
             </phone>
           </phones> 
           <email>bob@gmail.com</email>
           <spouse>1001</spouse>
         </contact>
       </entity>
       <match>
         <contact>
           <id>e6e1b847-d61a-46d9-a610-c678ba40ca41</id>
           <name>bob</name>
           <city>berwyn</city>
           <phones>
             <phone>
               <number>311 555-1234</number>
               <type>home</type>
             </phone>
             <phone>
               <number>311 555-4321</number>
               <type>mobile</type>
             </phone>
           </phones> 
           <email>bob@gmail.com</email>
           <spouse>1001</spouse> 
         </contact>
         <fuzzyMatchDetails>
           <field>name</field>
           <first>BOBBY</first>
           <second>BOB</second>
           <method>jarowinkler</method>
           <matchStrength>0.90666664</matchStrength>
           <threshold>0.85</threshold>
         </fuzzyMatchDetails>
       </match>
       <duplicate>
         <contact>
           <id>fc8cd5be-ac26-4e9a-9d0c-6b397a124172</id>
           <name>bob</name>
           <city>berwyn</city>
           <phones>
             <phone>
               <number>311 555-5678</number>
               <type>home</type>
             </phone>
             <phone>
               <number>311 555-8765</number>
               <type>mobile</type>
             </phone>
           </phones> 
           <email>bob@gmail.com</email>
           <spouse>1001</spouse>
         </contact>
         <fuzzyMatchDetails>
           <field>name</field>
           <first>BOBBY</first>
           <second>BOB</second>
           <method>jarowinkler</method>
           <matchStrength>0.90666664</matchStrength>
           <threshold>0.85</threshold>
         </fuzzyMatchDetails>
       </duplicate>
     </MatchResult>
     <MatchResult status="ALREADY_LINKED">
       <entity>
         <contact>
           <id>2</id>
           <name>mike</name>
           <city>chesterbrook</city>
           <phones>
             <phone>
               <number>311 555-2345</number>
               <type>home</type>
             </phone>
             <phone>
               <number>311 555-5432</number>
               <type>mobile</type>
             </phone>
           </phones> 
           <email>mike@gmail.com</email>
           <spouse>1002</spouse>
         </contact>
       </entity>
    </MatchResult>
  </MatchEntitiesResponse>
  

  For a result with status MATCH_REFERENCE_FAILURE, it omits the <match> element. The <entity> element is instead followed by <message>, which contains details about the match reference failure.

  Sample response body:

  
  <MatchEntitiesResponse>
     <MatchResult status="MATCH_REFERENCE_FAILURE">
       <entity>
         <contact>
           <id>1</id>
           <name>bobby</name>
           <city>berwyn</city>
           <phones>
             <phone>
               <number>311 555-1234</number>
               <type>home</type>
             </phone>
             <phone>
               <number>311 555-4321</number>
               <type>mobile</type>
             </phone>
           </phones> 
           <email>bob@gmail.com</email>
           <spouse>1313</spouse>
         </contact>
       </entity>
       <message>Unable to match on {spouse} field value '1313' because it does not resolve to a golden record.</message>
     </MatchResult>
  </MatchEntitiesResponse>

  For a result with status TOO_MANY_MATCHES, the response includes matched entities, match rounds, and fuzzy scores.

  Sample response body:

  <MatchEntitiesResponse>
  <MatchResult status="TOO_MANY_MATCHES" matchRule="Match on: gender AND Existing last_name is similar to (Jaro-Winkler) Incoming last_name AND Existing first_name is similar to (Jaro-Winkler) Incoming first_name">
    <entity>
      <person>
        <id>person1-SF</id>
        <first_name>Elvira</first_name>
        <last_name>Holden</last_name>
        <ssn>156-96-2973-</ssn>
        <email>JosephRSalazar@dodgit.com</email>
        <age>57</age>
        <dob>1967-05-13</dob>
        <gender>female</gender>
        <address>
          <street>3344 Nixon Avenue</street>
          <city>Ooltewah</city>
          <state>TN</state>
          <zipcode>37363</zipcode>
          <country>US</country>
          <latitude>35.054935</latitude>
          <longitude>-85.118251</longitude>
        </address>
        <phones>
          <phone>
            <type>Home</type>
            <number>423-238-8261</number>
          </phone>
        </phones>
        <vehicle>1994 Porsche 928</vehicle>
        <occupation>Terrazzo worker</occupation>
        <employer>Asian Fusion</employer>
        <username>Haided</username>
        <password>oF5aiqueu</password>
        <height>183</height>
        <weight>93.8</weight>
      </person>
    </entity>
    <match>
      <person>
        <id>102f8bdb-75b0-4c23-87ab-7d36c081a938</id>
        <first_name>Shirley</first_name>
        <last_name>Holden</last_name>
        <ssn>156-96-2972</ssn>
        <email>ShirleyJHolden@spambob.com</email>
        <age>55</age>
        <dob>1969-03-18</dob>
        <gender>female</gender>
        <address>
          <street>255 Watson Street</street>
          <city>Ventnor City</city>
          <state>NJ</state>
          <zipcode>08046</zipcode>
          <country>US</country>
          <latitude>39.250841</latitude>
          <longitude>-74.482126</longitude>
        </address>
        <phones>
          <phone>
            <type>Home</type>
            <number>609-822-2590</number>
          </phone>
        </phones>
        <vehicle>2001 Chevrolet Trans Sport</vehicle>
        <occupation>Marketing manager</occupation>
        <employer>The White Rabbit</employer>
        <username>Scance</username>
        <password>UShahwee5gai</password>
        <height>173.0</height>
        <weight>71.1</weight>
        <bff>667f523b-bccd-4632-b311-b8d405d4399d</bff>
      </person>
      <fuzzyMatchDetails>
        <field>last_name</field>
        <first>Holden</first>
        <second>Holden</second>
        <method>jarowinkler</method>
        <matchStrength>1.0</matchStrength>
        <threshold>0.85</threshold>
      </fuzzyMatchDetails>
      <fuzzyMatchDetails>
        <field>first_name</field>
        <first>Shirley</first>
        <second>Elvira</second>
        <method>jarowinkler</method>
        <matchStrength>0.53968257</matchStrength>
        <threshold>0.85</threshold>
      </fuzzyMatchDetails>
    </match>
    <match>
      <person>
        <id>1534a837-e13b-459c-bb8f-3f004bc799a1</id>
        <first_name>Frances</first_name>
        <last_name>Hodge</last_name>
        <ssn>392-20-0441</ssn>
        <email>FrancesJHodge@dodgit.com</email>
        <age>56</age>
        <dob>1968-07-18</dob>
        <gender>female</gender>
        <address>
          <street>3405 Hartland Avenue</street>
          <city>Appleton</city>
          <state>WI</state>
          <zipcode>54911</zipcode>
          <country>US</country>
          <latitude>44.252196</latitude>
          <longitude>-88.418601</longitude>
        </address>
        <phones>
          <phone>
            <type>Home</type>
            <number>920-381-5650</number>
          </phone>
        </phones>
        <vehicle>2003 Rover City</vehicle>
        <occupation>Instrumentation technician</occupation>
        <employer>Strategic Profit</employer>
        <username>Cinceres</username>
        <password>aih0jueK</password>
        <height>169.0</height>
        <weight>85.0</weight>
        <bff>0e16c88f-6a9c-48b9-a784-7163a78ad1b3</bff>
      </person>
      <fuzzyMatchDetails>
        <field>last_name</field>
        <first>Hodge</first>
        <second>Holden</second>
        <method>jarowinkler</method>
        <matchStrength>0.8577778</matchStrength>
        <threshold>0.85</threshold>
      </fuzzyMatchDetails>
      <fuzzyMatchDetails>
        <field>first_name</field>
        <first>Frances</first>
        <second>Elvira</second>
        <method>jarowinkler</method>
        <matchStrength>0.0</matchStrength>
        <threshold>0.85</threshold>
      </fuzzyMatchDetails>
    </match>
  </MatchResult>
  </MatchEntitiesResponse>

• 400 (Bad Request) The universeID parameter value contains only space characters. Sample response body:

<error>
  <message>The given universe id is blank.</message>
</error>

• 400 (Bad Request) The <batch> element’s src attribute value specifies a valid contributing source but the XML document contains invalid markup. Sample response body:

  <error>
    <message>When trying to parse a batch update for universe with id '851a6a64-6a88-4916-a5b7-d6a974d54318'.</message>
    <message>Unexpected EOF; was expecting a close tag for element <batch>
      at [row,col {unknown-source}]: [1,16]</message>
  </error> 

• 400 (Bad Request) The request body is empty. Sample response body:

  <error>
    <message>When trying to parse a batch update for universe with id '851a6a64-6a88-4916-a5b7-d6a974d54318'.</message>
    <message>Unexpected EOF in prolog at [row,col {unknown-source}]: [1,0]</message>
  </error> 

• 400 (Bad Request) The request body does not start with a <batch> tag. Sample response body:

  <error>
    <message>An update batch for universe with id '851a6a64-6a88-4916-a5b7-d6a974d54318' could not be processed because it starts with a 'foo' tag instead of with a 'batch' tag.</message>
  </error> 

• 400 (Bad Request) The <batch> element does not have a populated source src attribute. Sample response body:

  <error>
    <message>An update batch for universe with id '851a6a64-6a88-4916-a5b7-d6a974d54318' does not contain a source ('src') attribute.</message>
  </error> 

• 400 (Bad Request) The batch does not contain any source entities. Sample response body:

  <error>
        <message>The match request did not contain any entities.</message>
  </error>

• 404 (Not Found) universeID does not identify a universe under the authenticated account. Sample response body:

  <error>
    <message>A universe with id 'ac11cc59-c77a-4afe-8c92-ed86a7daabec' does not exist.</message>
    <message>Universe definition with id 'ac11cc59-c77a-4afe-8c92-ed86a7daabec' could not be loaded from plugin component directory 'plugins/mdm/bundles/ac11cc59-c77a-4afe-8c92-ed86a7daabec'.</message>
  </error> 

• 404 (Not Found) sourceID does not identify a source attached to the specified universe. Sample response body:

  <error>
    <message>Source with code 'FOO' does not exist under universe '851a6a64-6a88-4916-a5b7-d6a974d54318'.</message>
  </error> 

• 401 (Invalid Credentials) JWT auth token is expired. Sample response body:

  <body>
  <h2>HTTP ERROR 401</h2>
     <p>Problem accessing /mdm/universes. Reason:
     <pre>Invalid credentials.</pre>
  </p>
  </body>

• 403 (You do not have permissions to access this resource) User does not have the required MDM privilege to perform the action. Applicable to JWT auth only. Sample response body:

  <error><message>You do not have permissions to access this resource.</message></error>