Written and maintained by CASRAI Editorial Board
Last updated
The FHIR Organization, Practitioner, and PractitionerRole resources form the administrative directory triad in HL7 Fast Healthcare Interoperability Resources (FHIR) used to represent healthcare institutions, individual clinicians, and the specific clinical roles and locations in which those clinicians practice. Standardized under the HL7 US Core Implementation Guide and the HL7 Da Vinci PDEX Plan-Net Implementation Guide, these resources power CMS-mandated payer provider directories, health information exchange (HIE) endpoint lookups, and clinical trial site registries.
How Do FHIR Practitioner and PractitionerRole Model Healthcare Providers?
A foundational architectural principle in HL7 FHIR R4 (https://hl7.org/fhir/R4/administration-module.html) is the strict separation between a human healthcare worker’s identity (Practitioner) and their institutional affiliation, specialty, and practice location (PractitionerRole):
Practitioner(https://hl7.org/fhir/R4/practitioner.html): Represents the individual person involved in healthcare delivery or research (physician, nurse practitioner, pharmacist, therapist, or principal investigator) regardless of where they work. It stores the person’s legal name (`Practitioner.name`), individual Type 1 National Provider Identifier (`Practitioner.identifier`), state medical licenses and board certifications (`Practitioner.qualification`), and languages spoken (`Practitioner.communication`).Organization(https://hl7.org/fhir/R4/organization.html): Represents a formally recognized grouping of people or corporations—such as an integrated health system, hospital facility, academic department, medical group practice, clinical laboratory, health plan, or clinical trial sponsor. Hierarchical parent-child relationships (e.g., a cardiology department inside a university hospital) are modeled via `Organization.partOf`.PractitionerRole(https://hl7.org/fhir/R4/practitionerrole.html): Functions as the many-to-many join resource connecting one `Practitioner` (`PractitionerRole.practitioner`) to one `Organization` (`PractitionerRole.organization`) at one or more physical `Location` resources (`PractitionerRole.location`). It records the clinician’s role code (`code`), NUCC clinical specialty (`specialty`), scheduled availability (`availableTime`), Direct Secure Messaging or FHIR `Endpoint` (`endpoint`), and payer network participation.
This normalized three-resource design prevents data duplication when a physician practices at multiple hospitals: the clinician has a single Practitioner resource linked to two separate PractitionerRole instances, each with its own clinic address, phone number, and billing organization.
How Are NPI and TIN Identifiers Represented in FHIR Organization?
In US healthcare interoperability and revenue cycle workflows, matching provider entities across EHRs and claims requires slicing `Organization.identifier` and `Practitioner.identifier` using authoritative HL7 system URIs:
| Identifier Type | Target FHIR Resource | Official HL7 FHIR System URI | Clinical & Regulatory Purpose |
|---|---|---|---|
| NPI (Type 1 Individual) | Practitioner.identifier |
http://hl7.org/fhir/sid/us-npi |
10-digit HIPAA National Provider Identifier for individual clinicians (45 CFR § 162.406). |
| NPI (Type 2 Organizational) | Organization.identifier |
http://hl7.org/fhir/sid/us-npi |
10-digit HIPAA National Provider Identifier for hospitals, group practices, and Subpart clinics. |
| TIN / EIN (Taxpayer ID) | Organization.identifier |
http://hl7.org/fhir/sid/us-ein (or OID urn:oid:2.16.840.1.113883.4.4) |
9-digit IRS Employer Identification Number used for payer contracting and 837/835 tax reporting. |
| CLIA Number | Organization.identifier |
urn:oid:2.16.840.1.113883.4.7 |
Clinical Laboratory Improvement Amendments certification identifier required on lab results. |
| CCN (CMS Certification Number) | Organization.identifier |
http://hl7.org/fhir/sid/us-ccn |
6-character Medicare institutional provider number for hospitals, SNFs, and facilities. |
| NUCC Provider Taxonomy | PractitionerRole.specialty |
http://nucc.org/provider-taxonomy |
10-character alphanumeric specialty code (e.g., 207RC0000X for Cardiovascular Disease). |
Because a Taxpayer Identification Number (TIN) is sensitive financial metadata, public-facing provider directory APIs (such as Da Vinci Plan-Net) typically expose the Type 2 NPI (`http://hl7.org/fhir/sid/us-npi`) on `Organization` while restricting raw `us-ein` values to authenticated B2B claims and credentialing exchanges.
{
"resourceType": "Organization",
"id": "org-metro-cardiology",
"meta": {
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization"
]
},
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1992837465"
},
{
"system": "http://hl7.org/fhir/sid/us-ein",
"value": "04-3829104"
},
{
"system": "urn:oid:2.16.840.1.113883.4.7",
"value": "22D0948271"
}
],
"active": true,
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/organization-type",
"code": "prov",
"display": "Healthcare Provider"
}
]
}
],
"name": "Metro Academic Cardiology Associates",
"telecom": [
{
"system": "phone",
"value": "617-555-0190",
"use": "work"
}
],
"address": [
{
"line": ["450 Brookline Ave, Suite 300"],
"city": "Boston",
"state": "MA",
"postalCode": "02215",
"country": "US"
}
]
}How Are FHIR Directory Resources Used in Payer and HIE Provider Directories?
Under the CMS Interoperability and Patient Access Final Rule (CMS-9115-F) (https://www.cms.gov/priorities/key-initiatives/burden-reduction/interoperability), Medicare Advantage, Medicaid, CHIP, and Qualified Health Plan (QHP) issuers must publish a public, machine-readable Provider Directory API conforming to the HL7 Da Vinci PDEX Plan-Net Implementation Guide (https://hl7.org/fhir/us/davinci-pdex-plan-net/):
- Network and InsurancePlan Linking: Plan-Net profiles `Organization` into two distinct slices—
PlannetOrganization(for hospital systems, clinics, and payers) andPlannetNetwork(for specific provider networks)—linked to anInsurancePlanresource. - Specialty and Location Discovery via
_include: A single RESTful query retrieves all in-network cardiologists within a postal code along with their parent clinic organization and physical location:GET [base]/PractitionerRole?specialty=http://nucc.org/provider-taxonomy|207RC0000X&location.address-postalcode=02215&_include=PractitionerRole:practitioner&_include=PractitionerRole:organization&_include=PractitionerRole:location - Endpoint Discovery for TEFCA and Direct Messaging: Within HIEs and TEFCA Qualified Health Information Networks (QHINs), `Organization.endpoint` and `PractitionerRole.endpoint` reference FHIR `Endpoint` resources containing the FHIR base URL or DirectTrust S/MIME address needed to route clinical documents automatically.
Frequently Asked Questions
How do FHIR Practitioner and PractitionerRole model healthcare providers?
FHIR separates the individual clinician’s demographic identity, licenses, and Type 1 NPI into the Practitioner resource while using PractitionerRole as a join resource that links the Practitioner to a specific Organization, Location, NUCC clinical specialty, and electronic Endpoint.
How are NPI and TIN identifiers represented in FHIR Organization?
In US Core and Da Vinci profiles, an organization’s 10-digit Type 2 National Provider Identifier is stored in Organization.identifier with system URI http://hl7.org/fhir/sid/us-npi, while its 9-digit federal Taxpayer Identification Number (TIN/EIN) uses system URI http://hl7.org/fhir/sid/us-ein (or OID urn:oid:2.16.840.1.113883.4.4).
How are FHIR directory resources used in payer and HIE provider directories?
Payers and HIEs implement the HL7 Da Vinci PDEX Plan-Net Implementation Guide to expose Organization, Practitioner, PractitionerRole, Location, HealthcareService, and Endpoint resources via public RESTful APIs so patients and referring EHRs can query in-network specialists and electronic routing addresses in real time.
