The demographicsSearch web service is intended to retrieve one or more identities from Provider Data Management that are potential matches to the search input criteria.
Unlike the demographicsQuery web service (which returns only the single best-matching Provider Data Management identity if that identity matches above a match threshold), the demographicsSearch web service will return one-to-many Provider Data Management identities that have any degree of similarity to the search input criteria.
This allows you to do a fuzzy search to find any Provider Data Management identities that might be the person you are searching for, even if there are several identities that are returned in the search response.
*For customers with the Address Verification Service, please see the guide for additional data and API response information.
Sample URL
The URL for this request is of the format https://custXXXX-provider.verato-connect.com/provider-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.
-
{ "content": { "identity": { "addresses": [ { "city": "string", "postalCode": "string", "state": "string", "line2": "string", "line1": "string" } ], "locationInfo": [ { "coloCode": "string", "ruralUrbanSuburban": "string" } ], "education": [ { "gradYear": "string", "medSchool": "string" } ], "genders": [ "string" ], "phoneNumbers": [ { "number": "string", "type": "string" } ], "emails": [ "string" ], "license": [ { "number": "string", "state": "string", "taxonomyCode": "string", "licenseStatus": "string", "licenseStatusDetail": "string", "licenseEffectiveDate": "string", "licenseExpirationDate": "string", "licenseProfessionCode": "string", "licenseProfessionRankCode": "string", "licenseLastUpdateDate": "string" } ], "specialties": [ { "specialtyTaxonomyCode": "string" } ], "contactInformation": [ { "address": { "addressType": "string", "addressName": "string", "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string" }, "phoneList": [ { "type": " string ", "number": "string" } ], "faxList": [ { "type": "string", "number": "string" } ] } ], "disciplinaryInfo": [ { "exclusionType": "string", "warning": "string" } ], "groupTaxonomies": [ { "groupTaxonomyCode": "string" } ], "organizationNames": [ { "otherOrgName": "string", "legalBusinessName": "string", "parentOrgName": "string" } ], "names": [ { "middle": "string", "last": "string", "credential": "string", "prefix": "string", "suffix": "string", "first": "string" } ], "faxNumbers": [ { "number": "string", "type": "string" } ], "medicareInfo": [ { "inPecos": "string", "acceptsMedicare": "string" } ], "practiceInfo": [ { "estimatedPracticeYears": "string" } ], "authorizedOfficials": [ { "lastName": "string", "firstName": "string", "phoneNumber": "string", "namePrefix": "string", "nameCredential": "string", "nameSuffix": "string", "middleName": "string", "title": "string" } ], "npis": [ { "npi": "string", "entityTypeCode": "string" } ] }, "matchScoreThreshold": 0.0, "maxSearchResults": 10, "responseIdentityFormatNames": [ "string" ] }, "trackingId": "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.
- 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, "errors": "string", "trackingId": "string", "auditId": "string", "retryableError": boolean, "content": { "searchResults": [ { "linkId": "string", "identity": { "linkId": "string", "sources": [ { "name": "string", "id": "string" } ], "mergedSourceRecords": [ { "name": "string", "id": "string" } ], "names": [ { "first": "string", "middle": "string", "last": "string", "suffix": "string", "prefix": "string", "credential": "string" } ], "authorizedOfficials": [ { "title": "string", "phoneNumber": "string", "namePrefix": "string", "firstName": "string", "middleName": "string", "lastName": "string", "nameSuffix": "string", "nameCredential": "string" } ], "npis": [ { "npi": "string", "entityTypeCode": "string" } ], "license": [ { "number": "string", "state": "string", "taxonomyCode": "string", "licenseEffectiveDate": "string", "licenseExpirationDate": "string", "licenseStatus": "string", "licenseProfessionCode": "string", "licenseProfessionRankCode": "string", "licenseLastUpdateDate": "string", "licenseGrouping": "string", "licenseClassification": "string", "licenseSpecialization": "string" } ], "contactInformation": [ { "address": { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "addressType": "string", "addressName": "string" }, "phoneList": [ { "number": "string", "type": "string" } ], "faxList": [ { "number": "string", "type": "string" } ] } ], "specialties": [ { "specialtyTaxonomyCode": "string", "grouping": "string", "classification": "string", "specialization": "string" } ], "addresses": [ { "line1": " string", "line2": "string", "city": "string", "state": "string", "postalCode": "string" } ], "detailAddresses": [], "genders": [ "string" ], "emails": [ "string" ], "phoneNumbers": [ { "number": "string", "type": "string" } ], "faxNumbers": [ { "type": "string", "number": "string" } ], "disciplinaryInfo": [ { "warning": "string", "exclusionType": "string" } ], "medicareInfo": [ { "inPecos": "string", "acceptsMedicare": "string" } ], "education": [ { "medSchool": "string", "gradYear": "string" } ], "locationInfo": [ { "ruralUrbanSuburban": "string", "coloCode": "string" } ], "practiceInfo": [ { "estimatedPracticeYears": "string" } ], "groupTaxonomies": [ { "groupTaxonomyCode": "string" } ], "unmergeable": [], "organizationNames": [ { "otherOrgName": "string", "legalBusinessName": "string", "parentOrgName": "string”, } ], "alternateIdentifiers": [ { "state": "string", "type": "string", "value": "string", "issuer": "string" } ] }, "sameIdentity": "string", "matchScore": 0.00 } ] }, } -
{ "success": "string", "message": "string", "errors": "string", "trackingId": "string", "trackingId": "string", "auditId": UUID, "retryableError": boolean, "content": { "linkId": "string", "identityGroupedBySource": [ { "source": { "name": "string", "id": "string" }, "names": [ { "firstAsserted": "string", "lastAsserted": "string", "name": { "first": "string", "middle": "string", "last": "string", "suffix": "string", "prefix": "string", "credential": "string" } } ], "organizationNames": [ { "firstAsserted": "string", "lastAsserted": "string", "organization": { "legalBusinessName": "string", "otherOrgName": "string", "parentOrgName": "string" } } ], "npis": [ { "firstAsserted": "string", "lastAsserted": "string", "npiObject": { "npi": "string", "entityTypeCode": "string" } } ], "licenses": [ { "firstAsserted": "string", "lastAsserted": "string", "license": { "number": "string", "state": "string", "taxonomyCode": "string", "licenseEffectiveDate": "string", "licenseExpirationDate": "string", "licenseStatus": "string", "licenseProfessionCode": "string", "licenseProfessionRankCode": "string", "licenseLastUpdateDate": "string", "licenseGrouping": "string", "licenseClassification": "string", "licenseSpecialization": "string" } } ], "specialties": [ { "firstAsserted": "string", "lastAsserted": "string", "specialty": { "specialtyTaxonomyCode": "string", "grouping": "string", "classification": "string", "specialization": "string" } } ], "contactInformation": [ { "firstAsserted": "string", "lastAsserted": "string", "contactInformation": { "address": { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "addressType": "string", "addressName": "string" }, "phoneList": [ { "number": "string", "type": "string" } ], "faxList": [ { "type": "string", "number": "string" } ] } } ], "addresses": [ { "firstAsserted": "string", "lastAsserted": "string", "address": { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string" } }, "addressDetails": [], "genders": [ { "firstAsserted": "string", "lastAsserted": "string", "gender": "string" } ], "emails": [ { "firstAsserted": "string", "lastAsserted": "string", "email": "string" } ], "phoneNumbers": [ { "firstAsserted": "string", "lastAsserted": "string", "phoneNumber": { "number": "string", "type": "string" } } ], "faxNumbers": [ { "firstAsserted": "string", "lastAsserted": "string", "faxNumber": { "type": "string", "number": "string" } } ], "authorizedOfficials": [ { "firstAsserted": "string", "lastAsserted": "string", "authorizedOfficial": { "title": "string", "phoneNumber": "string", "namePrefix": "string", "firstName": "string", "middleName": "string", "lastName": "string", "nameSuffix": "string", "nameCredential": "string" } } ], "medicareInfo": [ { "firstAsserted": "string", "lastAsserted": "string", "medicareInfo": { "inPecos": "string", "acceptsMedicare": "string" } } ], "disciplinaryInfo": [ { "firstAsserted": "string", "lastAsserted": "string "disciplinaryInfo": { "warning": "string", "exclusionType": "string" } } ], "groupTaxonomies": [ { "firstAsserted": "string", "lastAsserted": "string", "groupTaxonomyCode": "string" } ], "education": [ { "firstAsserted": "string", "lastAsserted": "string", "education": { "medSchool": "string", "gradYear": "string" } } ], "locationInfo": [ { "firstAsserted": "string", "lastAsserted": "string", "locationInfo": { "ruralUrbanSuburban": "string", "coloCode": "string" } } ], "practiceInfo": [ { "firstAsserted": "string", "lastAsserted": "string", "practiceInfo": { "estimatedPracticeYears": "string" } ], "alternateIdentifiers": [ { "firstAsserted": "string", "lastAsserted": "string "alternateIdentifiers": { "state": "string", "type": "string", "value": "string", "issuer": "string" } } ] }, { "mergedSourceRecord": { "name": "string", "id": "string" } } ], "sameIdentity": "string", "matchScore": 0.00, } ] }, }