The demographicsSearch web service is intended to retrieve one or more identities from Universal Identity that are potential matches to the search input criteria.
Unlike the demographicsQuery web service (which returns only the single best-matching Universal identity if that identity matches above a match threshold), the demographicsSearch web service will return one-to-many identities that have any degree of similarity to the search input criteria.
This allows you to do a fuzzy search to find any identities that might be the person you are searching for, even if there are several identities that are returned in the search response.
Sample URL
The URL for this request is of the format https://custXXXX.verato-connect.com/link-ws/svc/demographicsSearch, where XXXX is a 4-digit number.
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 Identity. 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. The maximum results limit is capped at 100. Keep in mind that the response time for the web service will slow down as you get closer to the maximum results limit – setting a very large value 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", "country": "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 Link ID for the identity.
- The list of Source+Native ID values that are associated with the Link ID.
- The demographic attribute data for the identity (which may include attribute data from multiple source records matched together into this single Link ID). The format of this identity object will vary depending on which format was requested in the web service request JSON.
Note
Verato Universal Identity now offers real-time, CASS-certified U.S. address verification. When enabled, this feature enriches all addresses within the identity with extra details. These include residential status, vacancy status, extended ZIP code, geographical coordinates, and more. Every address in the API response will also contain additional fields, as detailed here. - The attribute sameIdentity is returned to represent whether or not the Identity is thought to be the same identity as provided in the request (Y= Yes, N= No, and U= Unknown).
- Y is returned if the associated score is at or above the configured Automatic Match threshold.
- U is returned for a score between the configured Automatic Match threshold, and at or above the Overlay Score threshold.
- N is returned for an extremely low score produced when comparing two distinctly different persons.
-
{ "success": boolean, "auditId": UUID, "retryableError": boolean, "message": "string", "errors": [ "string" ], "content": { "searchResults": [ { "linkId": "string", "sameIdentity": "string", "matchScore": 0, "identity": { "linkId": "string", "sources": [ { "name": "string", "id": "string" } ], "mergedSourceRecords": [], "names": [ { "first": "string", "last": "string" } ], "datesOfBirth": [ "string" ], "ssns": [ "string" ], "addresses": [ { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "country": "string" } ], "genders": [ "string" ], "emails": [ "string" ], "phoneNumbers": [ { "number": "string" } ], "unmergeable": [] } } ] } } -
{ "success": boolean, "auditId": UUID, "retryableError": boolean, "message": "string", "errors": [ "string" ], "content": { "searchResults": [ { "linkId": "string", "sameIdentity": "string", "matchScore": 0, "identityGroupedBySource": [ { "source": { "name": "string", "id": "string" }, "names": [ { "firstAsserted": "string", "lastAsserted": "string", "name": { "first": "string", "last": "string" } } ], "datesOfBirth": [ { "firstAsserted": "string", "lastAsserted": "string", "dateOfBirth": "1970-02-17" } ], "ssns": [ { "firstAsserted": "string", "lastAsserted": "string", "ssn": "string" } ], "addresses": [ { "firstAsserted": "string", "lastAsserted": "string", "address": { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "country": "string" } } ], "addressDetails": [], "genders": [ { "firstAsserted": "string", "lastAsserted": "string", "gender": "string" } ], "emails": [ { "firstAsserted": "string", "lastAsserted": "string", "email": "string" } ], "phoneNumbers": [ { "firstAsserted": "string", "lastAsserted": "string", "phoneNumber": { "countryCode": "string", "areaCode": "string", "number": "string" } } ] } ] } ] } }
demographicsSearch example 1
-
Suppose that you want to search your Universal Identity 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": "", "country": "" } ], "names": [ { "first": "JOHN", "last": "SMITH" } ], "ssns": [ "" ], "genders": [ "" ], "datesOfBirth": [ "" ], "phoneNumbers": [ { "number": "", "areaCode": "", "extension": "", "countryCode": "" } ] } } } -
Suppose you have 3 John Smiths in your Universal Identity instance – the response would look like this, where you have 3 distinct John Smith Universal Identity entities (each with a different Link ID) 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 Identity 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" ] } } ] } }