demographicsSearch

  • Web Services
  • UMPI
  • API Documentation

The demographicsSearch web service is intended to retrieve one or more identities from Universal MPI that are potential matches to the search input criteria.

Unlike the demographicsQuery web service (which returns only the single best-matching Universal MPI identity if that identity matches above a match threshold), the demographicsSearch web service will return one-to-many Universal MPI identities that have any degree of similarity to the search input criteria.

This allows you to do a fuzzy search to find any Universal MPI identities that might be the person you are searching for, even if there are several Universal MPI identities that are returned in the search response.

demographicsSearch request

  • The web service request includes:

    • A tracking ID (an optional identifier that the client can supply to track the response)
    • Demographic attribute data to be used to search for potential matching identities in Universal MPI. Each attribute and attribute cluster in the request may contain zero-to-many values – for example, you could include no phone number in the query request or multiple phone numbers in the query request.
    • An optional string indicating which format to use in grouping Identity information in the web service response. The format options are ‘DEFAULT’ or ‘GROUP_BY_SOURCE’. If left blank, the ‘DEFAULT’ format is assumed. The ‘DEFAULT’ format groups the Identity information into a single Identity object; the ‘GROUP_BY_SOURCE’ format groups the Identity information into one object for each source record (Source + Native ID)
    • A match score threshold to apply when filtering search results – any search results that score at or above this threshold are included in the web service response. This score threshold can range from
    • 0.0 to 1.0, where a 0.0 score indicates that the search result does not have any attribute data in common with the search input criteria and a 1.0 score indicates that the search result is a perfect match. If the web service request does not specify a match score threshold, then the threshold will be defaulted to 0.0, which means all search results will be returned.
    • A maximum results limit – the web service response will include the highest-scoring search results up to this limit. The maximum results limit is an integer greater than or equal to 1. If the web service request does not specify a maximum results limit, then the limit will be defaulted to 10. There is no limit on how large you can set the maximum results limit, but keep in mind that the response time for the web service will slow down as you increase the maximum results limit – setting a very large value such as 1000 will result in a very slow web service response.
  • {
      "trackingId": "string", 
      "content": {
        "responseIdentityFormatNames": ["string"], 
        "matchScoreThreshold":0.0, 
        "maxSearchResults":10,
        "identity": {
          "emails": [ 
            "string"
          ],
          "addresses": [
            {
              "line1": "string",
              "line2": "string",
              "city": "string",
              "state": "string", 
              "postalCode": "string"
            }
          ],
          "names": [
            {
              "first": "string",
              "middle": "string",
              "last": "string", 
              "suffix": "string"
            }
          ],
          "ssns": [ 
            "string"
          ],
          "genders": [ 
          "string"
          ],
          "datesOfBirth": [ 
            "string"
          ],
          "phoneNumbers": [
            {
              "number": "string",
              "areaCode": "string",
              "extension": "string",
              "countryCode": "string"
             }
           ]
         }
       }
    }
    

demographicsSearch JSON response

  • The web service response includes:

    • An echo of the same tracking ID from the request
    • Several Boolean and string values with more information about the success/failure of the service (see section 3.1 above for more information)
    • An array of identity objects, one identity for each of the search results. Each identity in the result set includes:
      • The match score of the identity based on the search input criteria. The match score can range from 0.0 to 1.0, and the identities are returned in order from highest-scoring to lowest-scoring.
      • The LinkID for the identity.
      • The list of Source+Native ID values that are associated with the LinkID.
      • The demographic attribute data for the identity (which may include attribute data from multiple source records matched together into this single LinkID). The format of this identity object will vary depending on which format was requested in the web service request JSON
  • {
    "trackingId": "string", 
      "content": {
        "responseIdentityFormatNames": ["string"], 
        "matchScoreThreshold":0.0, 
        "maxSearchResults":10,
        "identity": {
          "emails": [ 
            "string"
          ],
          "addresses": [
            {
              "line1": "string",
              "line2": "string",
              "city": "string",
              "state": "string", 
              "postalCode": "string"
            }
          ],
          "names": [
            {
              "first": "string",
              "middle": "string",
              "last": "string", 
              "suffix": "string"
            }
          ],
          "ssns": [ 
            "string"
          ],
          "genders": [ 
          "string"
          ],
          "datesOfBirth": [ 
            "string"
          ],
          "phoneNumbers": [
            {
              "number": "string",
              "areaCode": "string",
              "extension": "string",
              "countryCode": "string"
             }
           ]
         }
       }
    }
    
  • {
    "trackingId": "string",
      "auditId": UUID,
      "success": boolean,
      "retryableError": boolean,
      "message": "string",
      "errors": [
        "string"
      ],
      "content": {
        "searchResults": [
      {
        "matchScore": 0,
        "linkId": "string",
        "identityGroupedBySource": [
          {
            "emails": [
            {
              "email": "string",
              "lastAsserted": "string",
              "firstAsserted": "string"
            }
          ],
            "addresses": [
              {
                "address": {
                "city": "string",
                "postalCode": "string",
                "state": "string",
                "line2": "string",
                "line1": "string"
              },
                "lastAsserted": "string",
                "firstAsserted": "string"
              }
            ],
            "names": [
              {
                "name": {
                  "middle": "string",
                  "last": "string",
                  "suffix": "string",
                  "first": "string"
              },
                "lastAsserted": "string",
                "firstAsserted": "string"
              }
            ],
            "ssns": [
              {
                "ssn": "string",
                "lastAsserted": "string",
                "firstAsserted": "string"
              }
            ],
            "genders": [
              {
                "gender": "string",
                "lastAsserted": "string",
                "firstAsserted": "string"
              }
            ],
            "source": {
              "name": "string",
              "id": "string"
            },
            "datesOfBirth": [
              {
                "dateOfBirth": "string",
                "lastAsserted": "string",
                "firstAsserted": "string"
              }
            ],
            "phoneNumbers": [
              {
                "phoneNumber": {
                  "number": "string",
                  "areaCode": "string",
                  "extension": "string",
                  "countryCode": "string"
              },
              "lastAsserted": "string",
              "firstAsserted": "string"
              }
            ]
          }
        ]
       }
      ]
     }
    }  
    

demographicsSearch example 1

  • Suppose that you want to search your Universal MPI instance for any persons named ‘John Smith’. You expect there might be multiple people with that name, and you know that the search results will not tell you which single John Smith record is the person you are looking for – the results will simply show you all the John Smiths.

  • You would use the demographicsSearch web service, with a request that looks like this:

    {
      "trackingId": "my-first-test-search-2017-09-22",
      "content": {
        "responseIdentityFormatNames": ["DEFAULT"],
        "matchScoreThreshold":0.0,
        "maxSearchResults":10,
        "identity": {
          "emails": [
            ""
          ],
          "addresses": [
            {
              "line1": "",
              "line2": "",
              "city": "",
              "state": "",
              "postalCode": ""
            }
          ],
          "names": [
            {
              "first": "JOHN",
              "last": "SMITH"
            }
          ],
          "ssns": [
            ""
          ],
          "genders": [
            ""
          ],
          "datesOfBirth": [
            ""
          ],
          "phoneNumbers": [
            {
              "number": "",
              "areaCode": "",
              "extension": "",
              "countryCode": ""
            }
          ]
        }
      }
    }
  • Suppose you have 3 John Smiths in your Universal MPI instance – the response would look like this, where you have 3 distinct John Smith Universal MPI entities (each with a different LinkID) in the search results:

    {
      "trackingId": "my-first-test-search-2017-09-22",
      "auditId": "6dd464bf-4612-4fd7-bc3e-9b931aaff12d",
      "success": true,
      "retryableError": false,
      "content": {
        "searchResults": [
          {
            "matchScore": 0.58,
            "identity": {
              "linkId": "59ef4ab0013345c7c",
              "sources": [
                {
                  "name": "A",
                  "id": "123"
                }
              ],
              "names": [
                {
                  "first": "JOHN",
                  "middle": "ADAM",
                  "last": "SMITH"
                }
              ],
              "ssns": [
                "111-22-3333"
              ],
              "datesOfBirth": [
                "1988-02-14"
              ],
            },
          },
          {
            "matchScore": 0.58,
            "identity": {
              "linkId": "587a55f842328abe",
              "sources": [
                {
                  "name": "A",
                  "id": "456"
                }
              ],
              "names": [
                {
                  "first": "JOHN",
                  "middle": "J",
                  "last": "SMITH"
                }
              ],
              "ssns": [
                "222-33-4444"
              ],
              "datesOfBirth": [
                "1971-11-11"
              ],
            },
          },
          {
            "matchScore": 0.58,
            "identity": {
               "linkId": "59e4578176abe6ee",
              "sources": [
                {
                  "name": "B",
                  "id": "789"
                }
              ],
              "names": [
                {
                  "first": "JOHN",
                  "last": "SMITH"
                }
              ],
              "ssns": [
                "333-44-5555"
              ],
              "datesOfBirth": [
                "1991-05-15"
              ]
            }
          }
        ]
      }
    }
    

In this example, the three John Smith entities in the search results all had the same match score, because they were all equally similar to the search input criteria (which was simply the name John Smith). 

As you add or remove search input criteria, the match score of each search result will change up or down depending on how similar each search result is to the search input criteria.

The match score is determined by Verato’s matching algorithm, which evaluates the similarity of each search result against the search input criteria. It is the same matching algorithm used to determine when customer records that you add (post) into Universal MPI are matches to previously-added customer records. 

demographicsSearch example 2

  • Suppose that you continue to add more search input criteria to your previous search – you repeat the demographicsSearch web service, but this time you search using both the name ‘John Smith’ as well as the birth date ‘1988-02-15’.

    This birth date is very close to, but not exactly the same as, one of the John Smith search results from your original search – that specific John Smith entity should now appear with a higher match score in your search results, because it is more similar to your search input than the other 2 John Smith identities (which will have lower match scores).

  • Your web service REQUEST would include the ‘1988-02-15’ DOB value this time.

    Your web service RESPONSE would look like:

    {
      "trackingId": "my-second-test-search-2017-09-22",
      "auditId": "6dd464bf-4612-4fd7-bc3e-9b931aaff12d",
      "success": true,
      "retryableError": false,
      "content": {
       "searchResults": [
          {
            "matchScore": 0.673,
            "identity": {
              "linkId": "59ef4ab0013345c7c",
              "sources": [
                {
                  "name": "A",
                  "id": "123"
                }
              ],
              "names": [
                {
                  "first": "JOHN",
                  "middle": "ADAM",
                  "last": "SMITH"
                }
              ],
              "ssns": [
                "111-22-3333"
              ],
              "datesOfBirth": [
                "1988-02-14"
              ],
            },
          },
          {
            "matchScore": 0.524,
            "identity": {
              "linkId": "587a55f842328abe",
              "sources": [
                {
                  "name": "A",
                  "id": "456"
                }
              ],
              "names": [
                {
                  "first": "JOHN",
                  "middle": "J",
                  "last": "SMITH"
                }
              ],
              "ssns": [
                "222-33-4444"
              ],
              "datesOfBirth": [
                "1971-11-11"
              ],
            },
          },
          {
            "matchScore": 0.524,
            "identity": {
              "linkId": "59e4578176abe6ee",
              "sources": [
                {
                  "name": "B",
                  "id": "789"
                }
              ],
              "names": [
                {
                  "first": "JOHN",
                  "last": "SMITH"
                }
              ],
              "ssns": [
                "333-44-5555"
              ],
              "datesOfBirth": [
                "1991-05-15"
              ]
            }
          }
        ]
      }
    }  
    

demographicsSearch example 3

  • Suppose that you continue to add even more search input criteria to your previous search – you repeat the demographicsSearch web service again, but this time you search using the name ‘John Smith’, the birth date ‘1988-02-15’ and the SSN ‘111-22-3333’.

    This birth date is very close to, but not exactly the same as, one of the John Smith search results from your original search, and the SSN is the same as the first John Smith search result as well – that specific John Smith entity should now appear with an even higher match score in your search results, because it is more similar to your search input than the other 2 John Smith identities (which will have even lower match scores this time).

  • Your web service REQUEST would include the ‘111223333’ SSN value this time.

    Your web service RESPONSE would look like:

    {
      "trackingId": "my-third-test-search-2017-09-22",
      "auditId": "6dd464bf-4612-4fd7-bc3e-9b931aaff12d",
      "success": true,
      "retryableError": false,
      "content": {
        "searchResults": [
          {
            "matchScore": 0.953,
            "identity": {
              "linkId": "59ef4ab0013345c7c",
              "sources": [
                {
                  "name": "A",
                  "id": "123"
                }
              ],
              "names": [
                {
                  "first": "JOHN",
                  "middle": "ADAM",
                  "last": "SMITH"
                }
              ],
              "ssns": [
                "111-22-3333"
              ],
              "datesOfBirth": [
                "1988-02-14"
              ],
            },
          },
          {
            "matchScore": 0.5,
            "identity": {
              "linkId": "587a55f842328abe",
              "sources": [
                {
                  "name": "A",
                  "id": "456"
                }
              ],
              "names": [
                {
                  "first": "JOHN",
                  "middle": "J",
                  "last": "SMITH"
                }
              ],
              "ssns": [
                "222-33-4444"
              ],
              "datesOfBirth": [
                "1971-11-11"
              ],
            },
          },
          {
            "matchScore": 0.5,
            "identity": {
              "linkId": "59e4578176abe6ee",
              "sources": [
                {
                  "name": "B",
                  "id": "789"
                }
              ],
              "names": [
                {
                  "first": "JOHN",
                  "last": "SMITH"
                }
              ],
              "ssns": [
                "333-44-5555"
              ],
              "datesOfBirth": [
                "1991-05-15"
              ]
            }
          }
        ]
      }
    }