demographicsQuery

  • Web Services
  • API Documentation
  • Provider

This web service retrieves the single matching identity from Provider Data Management that matches the demographic data provided in the web service request.

The match determination is made using Verato’s referential matching algorithm, and a matching identity is only returned if the match scores above the same match threshold used for determining matches during the postIdentity add/update process.

Like the postIdentity web service, the query web services allow the client to provide a “tracking ID” string that is client-generated, which is echoed back in the web service response. This provides the ability to track specific web service requests/responses using a message identifier that is meaningful to the client. In addition to the “tracking ID” in the web service request, the content of the query request will vary across the three different query web services.

The web service response is consistent across all three (nativeIdQuery, identityQuery, demographicsQuery) of the query web services.

*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/demographicsQuery, where XXXX is a 4-digit number.

demographicsQuery request

  • The demoGraphicsQuery request is made up of demographic attribute data  used to find a matching identity in Provider Data Management. 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.

  • { 
      "trackingId": "string"   
      "content": { 
        "responseIdentityFormatNames": ["string"], 
        "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" 
            } 
          ], 
          "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" 
            } 
          ], 
          "groupTaxonomies": [ 
            { 
              "groupTaxonomyCode": "string" 
            } 
          ], 
          "authorizedOfficials": [ 
            { 
              "lastName": "string", 
              "firstName": "string", 
              "phoneNumber": "string", 
              "namePrefix": "string", 
              "nameCredential": "string", 
              "nameSuffix": "string", 
              "middleName": "string", 
              "title": "string" 
            } 
          ], 
          "npis": [ 
            { 
              "npi": "string", 
              "entityTypeCode": "string" 
            } 
          ] 
        } 
      } 

demographicsQuery JSON response

  • The 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
    • The Link ID of the identity returned from the query
    • An identity object consisting of both of the following:
      • The list of Source+Native ID values that are associated with the Link ID
      • The demographic attribute data for the overall Provider Data Management 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.
  • { 
        "success": boolean, 
        "message": "string”, 
        "content": { 
            "linkId": "string", 
            "identity": { 
                "linkId": "string", 
                "sources": [ 
                    { 
                        "name": "string", 
                        "id": "string" 
                    } 
                ], 
                "mergedSourceRecords": [], 
                "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" 
                ], 
                "genders": [ 
                    "string" 
                ], 
                "emails": [ 
                    "string" 
                ], 
                "phoneNumbers": [ 
                    { 
                        "number": "string", 
                        "type": "string" 
                    } 
                ], 
                "faxNumbers": [ 
                    { 
                        "type": "string", 
                        "number": "string" 
                    } 
                ], 
                "disciplinaryInfo": [ 
                    { 
                        "warning": "string", 
                        "exclusionType": "string" 
                    } 
                ], 
                "groupTaxonomies": [ 
                    { 
                        "groupTaxonomyCode": "string" 
                    } 
                ], 
                "medicareInfo": [ 
                    { 
                        "inPecos": "string", 
                        "acceptsMedicare": "string" 
                    } 
                ], 
                "education": [ 
                    { 
                        "medSchool": "string", 
                        "gradYear": "string" 
                    } 
                ], 
                "locationInfo": [ 
                    { 
                        "ruralUrbanSuburban": "string", 
                        "coloCode": "string" 
                    } 
                ], 
                "practiceInfo": [ 
                    { 
                        "estimatedPracticeYears": "string" 
                    } 
                ], 
                "unmergeable": [], 
                "organizationNames": [ 
                    { 
                        "legalBusinessName": "string", 
                        "parentOrgName": "string" 
                    } 
                ] 
            } 
        }, 
        "trackingId": "string", 
        "auditId": UUID, 
        "retryableError": boolean 
  • 
        { 
        "success": "string", 
        "message": "string", 
        "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" 
                            } 
                        } 
                    ] 
                } 
            ] 
        }, 
        "errors": "string", 
        "trackingId": "string", 
        "auditId": UUID, 
        "retryableError": boolean   
    }