POST/v3/live/healthcare/hcp/match

Match HCP

Accepts attributes and returns matching healthcare professionals

Version
v3
Rate limit
Tier 3 · 10–200 rps by plan
Billing
Healthcare (HCP) · Match HCP

Request body

Each filter is an object of and / or / not arrays. or boosts matches without excluding others; use and with a single value to filter.

  • affiliationNameobjectOptional
    Match on the name of an affiliated organization; low-value words are ignored and terms match in any order
  • aggkHcoIdobjectOptional
    Filter by the AggKnowledge HCO ID of an affiliated organization
  • aggkPersonIdobjectOptional
    Filter by AggKnowledge Person ID
  • designationsobjectOptional
    Filter by professional designation (e.g. MD, PhD); case-insensitive exact match
  • emailobjectOptional
    Filter by email address; case-insensitive exact match
  • gmcobjectOptional
    Filter by General Medical Council (GMC) reference number
  • npiobjectOptional
    Filter by National Provider Identifier (NPI)

    and is a hard filter only when strict is true; in the default ranked mode these values influence matching and ranking without excluding results.

    AND

    With strict: true, values that must all match; a value also in not is rejected with a 400, as is, on a field the record holds once, more than one distinct value or a value outside the field's or values. Otherwise treated the same as or

    OR
    1033479100

    With strict: true, values of which at least one must match; if every one is also in not, the request is rejected with a 400. Otherwise alternatives that resolve or rank the match, as strict describes

    NOT

    Values that must not match (hard exclusion), with or without strict

    Enter adds a value · Backspace on empty removes the last
  • orcidobjectOptional
    Filter by ORCID identifier
  • organizationNpiobjectOptional
    Filter by the National Provider Identifier (NPI) of an affiliated organization
  • rppsobjectOptional
    Filter by Répertoire Partagé des Professionnels de Santé (RPPS) number
  • specialtiesobjectOptional
    Filter by medical specialty; low-value words are ignored and terms match in any order
  • cityobjectOptional
    Filter by city; case-insensitive exact match
  • countryobjectOptional
    Filter by country; case-insensitive exact match
  • firstNamestringOptional
    Match on first name; phonetic and fuzzy matching
  • fullNamestringOptional
    Match on full name; combines exact, phonetic, and fuzzy matching
  • lastNamestringOptional
    Match on last name; phonetic and fuzzy matching
  • middleNamestringOptional
    Match on middle name; phonetic and fuzzy matching
  • postalCodeobjectOptional
    Filter by postal code; case-insensitive exact match
  • stateobjectOptional
    Filter by state or province; case-insensitive exact match
  • strictbooleanOptional
    When true, every supplied field is a hard filter: and values must all match, or values need at least one match, and the name fields must match. When false or omitted (the default), and and or are treated alike as alternatives. Any one value on an identifier field (npi, gmc, rpps, orcid, aggkPersonId, email) resolves the match, and the name fields then only rank; with no identifier, the name fields must match instead. Other fields only rank results, unless the request has neither an identifier nor a name, when at least one of their values must match. not values always exclude, and a request with only not values is rejected with a 400. With strict: true, a request is rejected with a 400 when any field has an and value that is also in not, or an or list whose every value is in not; fields a professional holds once (npi, orcid, aggkPersonId, city, state, country, postalCode) also accept at most one distinct and value, which must be among the field's or values when both are given.
  • metadataobjectOptional
    Optional metadata to associate with the request. Will be returned in the response.
Headers
x-api-key Required · API key for authentication

Response

  • resultsobject[]
    Matching healthcare professionals
    • affiliationsobject[]
      Affiliated healthcare organizations, one entry per distinct organization. A compact summary for disambiguation; fetch the HCP for full affiliation detail
    • aggkHcpIdstring
      AggKnowledge HCP ID
    • aggkPersonIdstring
      AggKnowledge Person ID
    • designationsstring[]
      Professional designations
    • firstNamestring
      First name
    • gmcstring
      General Medical Council (GMC) reference number
    • lastNamestring
      Last name
    • matchedOnstring[]
      Which of the supplied match criteria this result actually matched, named as the request fields you sent (e.g. npi, email, lastName). Use it to tell a result that matched on every criterion from one that matched on only some — a result can be returned on an identifier alone while other criteria did not match. A criterion is absent when it did not match or was not supplied; it is also absent when we hold no value for that field on the professional, so absence is not evidence of a conflict. not exclusions never appear. Sorted alphabetically.
    • npistring
      National Provider Identifier (NPI)
    • orcidstring
      ORCID identifier
    • patientCountinteger (int32)
      Patient count
    • rppsstring
      Répertoire Partagé des Professionnels de Santé (RPPS) number
    • scorenumber
      Relevance score for this match; higher indicates a stronger match. Results are ordered by score descending, so callers can auto-accept the top hit or review the top N. Scores are relative within a single response and not comparable across requests.
    • socialMediaUrlstring
      Social Media URL of the professional
    • socialProfilestring
      Social profile URL of the professional. The same value as socialMediaUrl, under the name the rest of v3 uses; prefer this one.
    • specialtiesobject[]
      Medical specialties
  • 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.
  • isRetryableboolean
    When isSuccess is false, whether sending the same input again could succeed. Always true when isSuccess is true.
  • 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.
  • metadataobject
    Caller-supplied metadata echoed back from the request.
  • inputParametersobject
    Caller-supplied inputs echoed back in the response

Status codes