POST/v3/live/healthcare/discover/hcps

Discover HCPs

Returns US healthcare professionals matching criteria on their claims (drugs, procedures, diagnoses), their trials, publications, congresses, industry payments and leaderboards, and who and where they are, with and/or/not semantics. Results are ordered by AggKnowledge HCP ID and paginated via the request's pagination object (page and size); size defaults to 1000 and is capped at 1000, and no more than 5000 total results can be paged through.

Version: v3
Rate limit: Tier 2 · 10–100 rps by plan
Billing: HEALTHCARE_DISCOVER · Discover HCPs

Request body

metadataobjectOptional
Optional metadata to associate with the request. Will be returned in the response.
orobject[]Optional
One or more filter groups. An HCP matches the request when they satisfy at least one group; within a group every block is ANDed
- congressesobjectOptional
  Congress sessions the HCP presented at
- diagnosesobjectOptional
  Conditions the HCP diagnosed or referred for
- industryobjectOptional
  Manufacturers the HCP received non-meal payments from, as reported to CMS Open Payments. A payment is a financial relationship, not evidence the HCP uses the product; use 'not' on manufacturers to screen out conflicts of interest
- leaderboardsobjectOptional
  The HCP's decile on per-indication leaderboards
- namestringOptional
  Name for this group. Echoed in matchedFilterGroups on every result the group produced, and in validate warnings about the group
- practiceSettingobjectOptional
  The kind of organization the HCP currently works at. An HCP carries every setting that applies
- prescribingobjectOptional
  Drugs the HCP prescribed or administered over the trailing twelve months
- proceduresobjectOptional
  Procedures the HCP performed or ordered
- professionalobjectOptional
  Who the HCP is and where they practice
- publicationsobjectOptional
  Publications the HCP authored, by MeSH topic
- trialsobjectOptional
  Clinical trials the HCP is linked to on the trial record
[ { "name": "tavr-trialists", "procedures": { "performed": { "or": [ "33361" ] }, "quarters": { "gte": "2025Q1", "lte": "2026Q2" } }, "trials": { "roles": { "or": [ "PRINCIPAL_INVESTIGATOR" ] }, "startYears": { "gte": 2020 } } }, { "name": "academic-cardiologists", "professional": { "specialty": { "or": [ "207RC0000X" ] }, "state": { "or": [ "New Hampshire" ] } }, "practiceSetting": { "or": [ "ACADEMIC" ] } } ]
paginationobjectOptional
Page-based pagination controls
- pageinteger (int32)Optional
  0-indexed page number (default 0). (page + 1) * size must not exceed 5,000
- sizeinteger (int32)Optional
  Results per page (default 1,000, maximum 1,000)

Headers: x-api-key Required · API key for authentication

Request

{
  "or": [
    {
      "name": "tavr-trialists",
      "procedures": {
        "performed": {
          "or": [
            "33361"
          ]
        },
        "quarters": {
          "gte": "2025Q1",
          "lte": "2026Q2"
        }
      },
      "trials": {
        "roles": {
          "or": [
            "PRINCIPAL_INVESTIGATOR"
          ]
        },
        "startYears": {
          "gte": 2020
        }
      }
    },
    {
      "name": "academic-cardiologists",
      "professional": {
        "specialty": {
          "or": [
            "207RC0000X"
          ]
        },
        "state": {
          "or": [
            "New Hampshire"
          ]
        }
      },
      "practiceSetting": {
        "or": [
          "ACADEMIC"
        ]
      }
    }
  ],
  "pagination": {
    "page": 0,
    "size": 100
  }
}

2 of 3 parameters set. Edit values inline or add more from the list.

Response

hasProblemsboolean
Whether we hit a problem answering the request: the profile or company wasn't found, or a data source failed or timed out. Data may be missing or incomplete; problems, where the response has it, says which.
isRetryableboolean
When isSuccess is false, whether sending the same input again could succeed. Always true when isSuccess is true.
isSuccessboolean
true when the request was answered with a result. false means no result was returned: check isRetryable, which is true when a data source failed or timed out and false when the input matched nothing.
metadataobject
Caller-supplied metadata echoed back from the request.
paginationobject
The page and page size this response holds
resultsobject[]
HCPs matching the search criteria, ordered by AggKnowledge HCP ID
warningsstring[]
Non-fatal warnings about the search, such as a brand, ingredient or class that expands to more values than are searched

Status codes

Response

Example

{
  "results": [
    {
      "aggkHcpId": "169067854124029421",
      "npi": "1033479100",
      "fullName": "jay patel",
      "primarySpecialty": "Advanced Heart Failure and Transplant Cardiology",
      "city": "Dover",
      "state": "New Hampshire",
      "postalCode": "03820",
      "matchedCriteria": [
        {
          "group": "tavr-trialists",
          "field": "procedures.performed",
          "value": "33361"
        },
        {
          "group": "tavr-trialists",
          "field": "trials.roles",
          "value": "PRINCIPAL_INVESTIGATOR"
        }
      ],
      "matchedFilterGroups": [
        "tavr-trialists"
      ]
    }
  ],
  "pagination": {
    "page": 0,
    "size": 100
  },
  "warnings": [],
  "hasProblems": false,
  "isRetryable": true,
  "isSuccess": true,
  "metadata": {}
}