---
title: "Search using demographic information (demographicsSearch)"
method: POST
path: "/demographicsSearch"
---

# Search using demographic information (demographicsSearch)

`POST /demographicsSearch`

Searches Verato using the provided demographic and provider attributes. It returns zero or more candidate identities ordered by match score.

## Request body

- ServiceRequestDemographicsSearch — Standard wrapper for all service requests.
  - `trackingId` string — Optional client-defined correlation ID.
  - `content` DemographicsSearchWsRequest — Request for demographics-based search (multi-match).
    - `identity` Identity, required — Unified identity representation containing the properties common to Practitioner (Type 1) and Health Facility (Type 2) provider identities. Type-specific properties (e.g., `names`, `practitionerRoles` for Practitioner; `organizationNames`, `authorizedOfficials` for Health Facility) are also accepted on this object — see the request examples for the full shape per type.
      - `sources` PostIdentitySource[], required — The data source that provided this identity. Exactly one source is required per request.
        - `date` string, date
        - `name` string — Unique source system name across Verato.
        - `id` string — Native ID of the identity within the source.
        - `customerMetaData` CustomerMetaData — Optional metadata about the transaction that produced this identity record.
          - `transactionType` string — Type of transaction (e.g., INSERT, UPDATE).
          - `sourceLoginName` string — Login name of the user or system that submitted the record.
          - `sourceUserName` string — Display name of the user or system that submitted the record.
          - `transactionDateTime` string — Timestamp of the transaction in the Verato system (ISO 8601).
          - `sourceTransactionDateTime` string — Timestamp of the transaction in the source system (ISO 8601).
          - `customMetaData` object — Arbitrary key-value pairs for customer-defined metadata.
          - `location` string — Logical location or system identifier where the transaction originated.
      - `contactInformation` ContactInformationGrouped[]
        - `address` Address — Standalone address representation.
          - `addressName` string
          - `addressType` string
          - `line1` string
          - `line2` string
          - `city` string
          - `district` string
          - `state` string
          - `postalCode` string
          - `country` string
          - `latitude` number
          - `longitude` number
          - `validFrom` string, date
          - `validTo` string, date
        - `phoneList` PhoneNumber[]
          - `number` string — Phone number including country code and extension.
          - `type` string
          - `validFrom` string, date
          - `validTo` string, date
        - `faxList` FaxNumber[]
          - `number` string
          - `type` string
          - `validFrom` string, date
          - `validTo` string, date
        - `bestTimeToContact` BestTimeToContact[]
          - `day` string — Day-of-week code.
          - `startTime` string, time
          - `endTime` string, time
          - `allDay` boolean
      - `addresses` Address[]
        - `addressName` string
        - `addressType` string
        - `line1` string
        - `line2` string
        - `city` string
        - `district` string
        - `state` string
        - `postalCode` string
        - `country` string
        - `latitude` number
        - `longitude` number
        - `validFrom` string, date
        - `validTo` string, date
      - `phoneNumbers` PhoneNumber[]
        - `number` string — Phone number including country code and extension.
        - `type` string
        - `validFrom` string, date
        - `validTo` string, date
      - `faxNumbers` FaxNumber[]
        - `number` string
        - `type` string
        - `validFrom` string, date
        - `validTo` string, date
      - `emails` EmailAddress[]
        - `email` string, email
        - `type` string
        - `validFrom` string, date
        - `validTo` string, date
      - `npis` NPI[]
        - `npi` string
        - `entityTypeCode` string
        - `deactivationDate` string, date
      - `license` LicenseSimple[]
        - `number` string
        - `state` string
        - `taxonomyCode` string
        - `licenseEffectiveDate` string, date
        - `licenseExpirationDate` string, date
        - `licenseStatus` string
        - `licenseStatusDetail` string
        - `licenseProfessionCode` string
        - `licenseProfessionRankCode` string
        - `licenseLastUpdateDate` string, date
        - `licenseProfessionDescription` string
        - `licenseType` string
        - `licensePrimary` string
      - `specialties` SpecialtySimple[]
        - `specialtyTaxonomyCode` string
      - `qualifications` Qualification[]
        - `type` string
        - `qualification` string
        - `status` string
        - `issuer` string
        - `issueDate` string, date
        - `validFrom` string, date
        - `validTo` string, date
      - `alternateIdentifiers` AlternateIdentifier[]
        - `description` string
        - `type` string
        - `value` string
        - `status` boolean
        - `issuer` string
        - `issueDate` string, date
        - `startDate` string, date
        - `endDate` string, date
      - `externalUniqueIdentifier` ExternalUniqueIdentifier[]
        - `issuer` string
        - `value` string
        - `status` string
        - `startDate` string, date
        - `endDate` string, date
    - `matchScoreThreshold` number, double
    - `maxSearchResults` integer
    - `responseIdentityFormatNames` string[]

## Response `200`

Demographics search response

- ServiceResponseDemographicsSearch — Standard wrapper for all service responses.
  - `auditId` string — Unique audit identifier for correlating requests and responses.
  - `success` boolean — Indicates whether the business operation succeeded.
  - `warnings` string[] — Non-fatal warnings generated by the operation.
  - `retryableError` boolean — Indicates whether an error is transient and the request may be retried.
  - `message` string — Human-readable status message.
  - `errors` string[] — Error messages if success is false.
  - `trackingId` string — Echo of the request trackingId, if provided.
  - `content` DemographicsSearchWsResponse — Demographics search response content.
    - `searchResults` DemographicsSearchResult[]
      - `identityGroupedBySource` IdentityPerSource[]
        - `source` Source — Tracks an identity back to its source system.
          - `date` string, date
          - `name` string — Unique source system name across Verato.
          - `id` string — Native ID of the identity within the source.
        - `addresses` Address[]
          - `addressName` string
          - `addressType` string
          - `line1` string
          - `line2` string
          - `city` string
          - `district` string
          - `state` string
          - `postalCode` string
          - `country` string
          - `latitude` number
          - `longitude` number
          - `validFrom` string, date
          - `validTo` string, date
        - `names` PractitionerName[]
          - `use` string — Name usage code (e.g., official, nickname).
          - `prefix` string
          - `first` string
          - `middle` string
          - `last` string
          - `suffix` string
          - `credential` string
        - `phoneNumbers` PhoneNumber[]
          - `number` string — Phone number including country code and extension.
          - `type` string
          - `validFrom` string, date
          - `validTo` string, date
        - `faxNumbers` FaxNumber[]
          - `number` string
          - `type` string
          - `validFrom` string, date
          - `validTo` string, date
        - `emails` EmailAddress[]
          - `email` string, email
          - `type` string
          - `validFrom` string, date
          - `validTo` string, date
        - `licenses` LicenseSimple[]
          - `number` string
          - `state` string
          - `taxonomyCode` string
          - `licenseEffectiveDate` string, date
          - `licenseExpirationDate` string, date
          - `licenseStatus` string
          - `licenseStatusDetail` string
          - `licenseProfessionCode` string
          - `licenseProfessionRankCode` string
          - `licenseLastUpdateDate` string, date
          - `licenseProfessionDescription` string
          - `licenseType` string
          - `licensePrimary` string
        - `specialties` SpecialtySimple[]
          - `specialtyTaxonomyCode` string
        - `nPIs` NPI[]
          - `npi` string
          - `entityTypeCode` string
          - `deactivationDate` string, date
        - `medicareInfo` MedicareInfoSimple[]
          - `inPecos` boolean
          - `acceptsMedicare` boolean
        - `disciplinaryInfo` DisciplinaryInfoSimple[]
          - `warning` boolean
          - `exclusionType` string
        - `practiceInfo` PracticeInfoSimple[]
          - `estimatedPracticeYears` integer
        - `locationInfo` LocationInfoSimple[]
          - `ruralUrbanSuburban` string
          - `coloCode` string
        - `groupTaxonomies` GroupTaxonomySimple[]
          - `groupTaxonomyCode` string
        - `organizationNames` OrganizationNames[]
          - `legalBusinessName` string
          - `otherOrgName` string
          - `tradingName` string
          - `parentOrgName` string
        - `authorizedOfficials` AuthorizedOfficialSimple[]
          - `title` string
          - `prefix` string
          - `first` string
          - `middle` string
          - `last` string
          - `suffix` string
          - `credential` string
          - `phoneNumber` string
        - `mergedSourceRecord` MergedSourceRecord — Retired source record enriched with linkage metadata.
          - `date` string, date
          - `name` string
          - `id` string
          - `activeNativeId` string
          - `activeSource` string
          - `timestamp` string — Merge timestamp (UTC, ISO_LOCAL_DATE_TIME).
        - `softDeletedSourceRecord` Source — Tracks an identity back to its source system.
          - `date` string, date
          - `name` string — Unique source system name across Verato.
          - `id` string — Native ID of the identity within the source.
      - `matchScore` number, double, required
      - `customerSources` string[]
      - `linkId` string
      - `identity` Identity — Unified identity representation containing the properties common to Practitioner (Type 1) and Health Facility (Type 2) provider identities. Type-specific properties (e.g., `names`, `practitionerRoles` for Practitioner; `organizationNames`, `authorizedOfficials` for Health Facility) are also accepted on this object — see the request examples for the full shape per type.
        - `sources` PostIdentitySource[], required — The data source that provided this identity. Exactly one source is required per request.
          - `date` string, date
          - `name` string — Unique source system name across Verato.
          - `id` string — Native ID of the identity within the source.
          - `customerMetaData` CustomerMetaData — Optional metadata about the transaction that produced this identity record.
            - `transactionType` string — Type of transaction (e.g., INSERT, UPDATE).
            - `sourceLoginName` string — Login name of the user or system that submitted the record.
            - `sourceUserName` string — Display name of the user or system that submitted the record.
            - `transactionDateTime` string — Timestamp of the transaction in the Verato system (ISO 8601).
            - `sourceTransactionDateTime` string — Timestamp of the transaction in the source system (ISO 8601).
            - `customMetaData` object — Arbitrary key-value pairs for customer-defined metadata.
            - `location` string — Logical location or system identifier where the transaction originated.
        - `contactInformation` ContactInformationGrouped[]
          - `address` Address — Standalone address representation.
            - `addressName` string
            - `addressType` string
            - `line1` string
            - `line2` string
            - `city` string
            - `district` string
            - `state` string
            - `postalCode` string
            - `country` string
            - `latitude` number
            - `longitude` number
            - `validFrom` string, date
            - `validTo` string, date
          - `phoneList` PhoneNumber[]
            - `number` string — Phone number including country code and extension.
            - `type` string
            - `validFrom` string, date
            - `validTo` string, date
          - `faxList` FaxNumber[]
            - `number` string
            - `type` string
            - `validFrom` string, date
            - `validTo` string, date
          - `bestTimeToContact` BestTimeToContact[]
            - `day` string — Day-of-week code.
            - `startTime` string, time
            - `endTime` string, time
            - `allDay` boolean
        - `addresses` Address[]
          - `addressName` string
          - `addressType` string
          - `line1` string
          - `line2` string
          - `city` string
          - `district` string
          - `state` string
          - `postalCode` string
          - `country` string
          - `latitude` number
          - `longitude` number
          - `validFrom` string, date
          - `validTo` string, date
        - `phoneNumbers` PhoneNumber[]
          - `number` string — Phone number including country code and extension.
          - `type` string
          - `validFrom` string, date
          - `validTo` string, date
        - `faxNumbers` FaxNumber[]
          - `number` string
          - `type` string
          - `validFrom` string, date
          - `validTo` string, date
        - `emails` EmailAddress[]
          - `email` string, email
          - `type` string
          - `validFrom` string, date
          - `validTo` string, date
        - `npis` NPI[]
          - `npi` string
          - `entityTypeCode` string
          - `deactivationDate` string, date
        - `license` LicenseSimple[]
          - `number` string
          - `state` string
          - `taxonomyCode` string
          - `licenseEffectiveDate` string, date
          - `licenseExpirationDate` string, date
          - `licenseStatus` string
          - `licenseStatusDetail` string
          - `licenseProfessionCode` string
          - `licenseProfessionRankCode` string
          - `licenseLastUpdateDate` string, date
          - `licenseProfessionDescription` string
          - `licenseType` string
          - `licensePrimary` string
        - `specialties` SpecialtySimple[]
          - `specialtyTaxonomyCode` string
        - `qualifications` Qualification[]
          - `type` string
          - `qualification` string
          - `status` string
          - `issuer` string
          - `issueDate` string, date
          - `validFrom` string, date
          - `validTo` string, date
        - `alternateIdentifiers` AlternateIdentifier[]
          - `description` string
          - `type` string
          - `value` string
          - `status` boolean
          - `issuer` string
          - `issueDate` string, date
          - `startDate` string, date
          - `endDate` string, date
        - `externalUniqueIdentifier` ExternalUniqueIdentifier[]
          - `issuer` string
          - `value` string
          - `status` string
          - `startDate` string, date
          - `endDate` string, date
      - `sameIdentity` 'Y' | 'U' | 'N', required — Ternary value indicating yes/no/unknown.
      - `domains` Domain[]
        - `id` string — Domain identifier.
        - `name` string — Domain name.
      - `customizedIdentities` ObjectMap — Map of string keys to arbitrary JSON values.

---

[API](https://skmtc.net/verato/apis/verato-provider-api.md) · [All operations](https://skmtc.net/verato/apis/verato-provider-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/verato/verato-provider-api/versions/adc923264a6f/schema)