Matching

Lead with the strongest identifier you hold. Everything else only sharpens the ranking. Match HCP resolves your input to a professional. An authoritative identifier resolves the record on its own; the softer fields reorder candidates and never remove one.

Why it matters: you never have to hold back correct context to avoid an empty result. An NPI with a slightly wrong name still returns the NPI’s record. Results come ordered by score, descending, so auto-accept the top hit or review the top few.

  • Identifiers anchor: npi, gmc, rpps, orcid, aggkPersonId, and the near-unique email. Supply one and the record surfaces even when nothing else lines up. aggkPersonId is the person link: pass the ID you already hold from Enrich or Match to get the professional behind it.
  • Name anchors when you have no identifier. fullName, firstName, middleName, and lastName match exact, accent-insensitive, phonetic, and edit-distance forms, so a minor misspelling still resolves.
  • Attributes rank: specialties, designations, city, state, country, postalCode, and the affiliation fields affiliationName, aggkHcoId, and organizationNpi. A stale specialty ranks the right person lower instead of removing them.
  • Exception: not values are hard exclusions on every field, and strict: true makes every supplied field a hard filter, the legacy behavior: and values must all match, and or values need at least one.
  • Tag your requests. metadata attaches your own key/value pairs and is echoed back in the response.

Common matches#

1. By identifier. A registry identifier resolves to a single professional. Adding a name confirms the hit and cannot exclude it.

Match HCP · request body
{
  "npi": { "or": ["1033479100"] },
  "fullName": "jay patel"
}
Response
{
  "results": [
    {
      "affiliations": [
        { "aggkHcoId": "187892874929524688", "name": "Wentworth - Douglass Hospital" }
      ],
      "aggkHcpId": "169067854124029421",
      "aggkPersonId": "731209846",
      "designations": ["MD"],
      "firstName": "Jay",
      "gmc": null,
      "lastName": "Patel",
      "npi": "1033479100",
      "orcid": "0000-0002-0947-6676",
      "patientCount": 327,
      "rpps": null,
      "score": 60.0,
      "specialties": [
        { "cui": null, "name": "Advanced Heart Failure and Transplant Cardiology" },
        { "cui": null, "name": "Addiction Medicine" },
        { "cui": null, "name": "Cardiovascular Disease" }
      ]
    }
  ]
}

2. By name and specialty. With only a name, add a specialty (and a location if you have one) to rank look-alikes higher.

Match HCP · request body
{
  "fullName": "jay patel",
  "specialties": { "or": ["cardiovascular disease"] }
}
Response
{
  "results": [
    {
      "affiliations": [
        { "aggkHcoId": "187892874929524688", "name": "Wentworth - Douglass Hospital" }
      ],
      "aggkHcpId": "169067854124029421",
      "aggkPersonId": "731209846",
      "designations": ["MD"],
      "firstName": "Jay",
      "gmc": null,
      "lastName": "Patel",
      "npi": "1033479100",
      "orcid": "0000-0002-0947-6676",
      "patientCount": 327,
      "rpps": null,
      "score": 18.0,
      "specialties": [
        { "cui": null, "name": "Advanced Heart Failure and Transplant Cardiology" },
        { "cui": null, "name": "Addiction Medicine" },
        { "cui": null, "name": "Cardiovascular Disease" }
      ]
    }
  ]
}

3. By name and affiliation. A claim, a referral, or a directory entry names the person and where they practice. Send the organization as affiliationName (low-value words are ignored and terms match in any order), or as aggkHcoId / organizationNpi when you hold the identifier from Match HCO. Every result echoes its affiliations, so look-alike names are tellable apart without a follow-up lookup.

Match HCP · request body
{
  "fullName": "jay patel",
  "affiliationName": { "or": ["wentworth douglass hospital"] }
}