National Directory of Healthcare Providers & Services (NDH) Implementation Guide, published by HL7 International / Patient Administration. This guide is not an authorized publication; it is the continuous build for version 2.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-us-ndh/ and changes regularly. See the Directory of published versions

National Directory API Use Cases

Support discovery of electronic service information to enable the electronic exchange of information.

Electronic Service Information can be discovered by using any combination of data elements in a NDH entry using a fully qualified query to discover zero or more resulting records. These data elements in a query can include demographic data, geographic data, individual provider data, specialty data, National Provider Identity (NPI), organization, Tax Identification Number (TIN), etc. The results may include no records, one record, or multiple records

Use Case Actors

This diagram illustrates the interactions of various actors with the National Directory for Healthcare (NDH).

Information Flow

This diagram shows the information flow for this Use Case including the major senders and receivers (Actors) involved and the type(s) of information shared.

An Actor seeking Electronic Service Information sends a fully qualified query to the NDH. The query may include any combination of data elements, and may also include relative constructs such as “within 20 miles.” Queries may include partial values and may include inexact matches. The NDH processes the query and returns zero or more results to the Actor that sent the query. The results returned can include all or part of the record. The NDH should support queries including in the table below, but not necessarily limited to:

The NDH Consumer application help patients seeking healthcare providers

Use case: A patient seeks orthopedic services by using the NDH consumer application online

This scenario involves an individual looking for an orthopedic surgeon associated with the Hartford Orthopedics Group, which provides orthopedic care as part of the Acme of CT network HMO insurance plan at Hartford General Hospital. Hartford Orthopedics has two distinct locations, each with specific criteria for accepting new patients. The individual aims to select the facility that best matches the individual specific needs and availability. Additionally, the individual is interested in finding out the service hours of the location he choose.

The FHIR Resources are used to support this use case:

• PractitionerRole
• InsurancePlan
• Organization
• Location
• Network

Begin the search by identifying the practitionerRole for both the practitioner and the organization; next, locate the network associated with this role that corresponds with the insurance plan's network. Then, identify the locations linked to this practitionerRole, and determine if these locations are accepting new patients and what their operating hours are.

Utilize the NDH to locate endpoints for payer-to-payer API interactions

For the successful implementation of a Payer-to-Payer API, it is essential to establish and maintain a rigorous procedure for endpoint verification. This procedure ensures that access to and interaction with the API is restricted to authenticated healthcare organizations. The national directory provides a listing of payer information and their connections.

In the National Directory, a payer is identified as an organization classified under the type "payer." A unique identifier is assigned to a payer when it attests to the National Directory. The National Directory confirms the accuracy of the payer's details directly from the primary source. To verify the accuracy of the data, the payer's resource includes an element that indicates its verification status. Each payer may have multiple endpoints to support the functionality of the Payer-to-Payer API. Through a member matching process, a new payer can locate an existing payer in the National Directory and discover its associated endpoints. For endpoints that use mutual TLS (mTLS), the endpoint contains the mutual TLS public certificate which is shared to facilitate mutual TLS connections. Additionally, the payer's endpoint could be the UDAP well known endpoint if the payer organization supports UDAP.

The resources employed for these scenarios include:

• Endpoint
• Organization

To find a payer organization and associate endpoints:

GET [base]/Organization?type=payer&name=Florida Blue&_include:Organization:endpoint

Utilize the NDH to verify the legitimacy of requesting providers for Provider API interactions

To facilitate the Provider API, it's crucial to verify the legitimacy of requesting providers once a payer has confirmed their member relationship with a provider. This verification should take place during the provider's initial attempt to connect to the payer's API endpoint. Before granting access, the payer might require certain information and impose specific conditions for connectivity to ensure that only legitimate, legally authorized organizations can access the endpoint. Establishing a systematic process for endpoint connectivity is essential for Provider Access interactions. Payers can manage this process in-house or delegate it to a chosen vendor. While each payer might maintain its own directory, essential verification data, such as the provider's identity, service locations, and EHR data access endpoints, should be obtainable from the National Directory.

Providers may affiliate with multiple organizations (such as several hospitals) and practice at various locations within the same organization. The National Directory provides accurate details of a provider's relationships, including their practice locations, affiliated organizations, network status with health plans, and endpoints for information exchange.

The resources employed for these scenarios include:

• Practitioner
• PractitionerRole
• Organization
• Network
• InsurancePlan
• Location
• Endpoint

An endpoint for a provider could be supplied by the associated organization (hospital), a specific endpoint for a given role, or an endpoint at the location where the practitioner provides the service.

Utilize the NDH to find a practitioner practice with multiple organizations

A practitioner who works across various hospitals can engage in the CMS Merit-based Incentive Payment System (MIPS) for quality measures. The process involves gathering and submitting data from numerous locations. The National Directory of Health (NDH) catalogues every association the practitioner holds with the hospitals they serve. This comprehensive listing aids third parties in locating all necessary endpoints to aggregate the data efficiently.

The resources employed for these scenarios include:

• Practitioner
• PractitionerRole
• Organization

Utilize the NDH to find a practitioner and the practitioner's endpoint for payer

Payers may need to locate an in-network provider and the endpoint of that provider. A provider could operate across multiple locations, being an in-network provider at one location but not at another. Here is an example illustrating this situation.

A practitioner is affiliated with an organization that has two locations. One location falls within the coverage area of an insurance plan, while the other is outside of it. This insurance plan is managed by an insurance network. To accommodate this situation, two distinct practitioner roles have been established. One role is linked to the insurance network, whereas the other is not. The PractitionerRole resource connects the practitioner, organization, network, location, and endpoint. This diagram aims to help payers in identifying both the provider and the provider's endpoint accurately.

Use cases for supporting HIE networks

NDH adopts the approach proposed in the IHE White Paper "Document Sharing Across Network Topologies" by utilizing the NDH OrganizationAffiliation resource to accommodate the various scenarios for federated, multi-hop, and proxied Endpoints. Specifically, we address how to represent the structure in the National Directory and ensure the successful execution of federated transactions, such as sending an XDR (Cross-Enterprise Document Reliable Interchange) push to a Document Recipient, intended for one or more recipients. The approach also includes implementing specific mechanisms to solve particular problems, allowing each environment to only adopt the mechanisms it requires. For instance, if a directory can declare that all Organization.partOf relationships imply the flow of federated data, the OrganizationAffiliation profile may not be necessary. It is essential to ensure that all mechanisms work seamlessly together within the National Directory, taking into account multiple networks and perspectives.

The key to this approach is the HIE-specific codes for OrganizationAffiliation.code, which are explained in the CodeSystem: Organization Affiliation Role for HIE . These codes are added to the value set for the NDH profile for OrganizationAffiliation.

The National Directory provides multiple perspectives based on access, without relying on selective visibility. This means that all consumers, regardless of their perspective, can view all details in the National Directory. Here is an Example from IHE "Document Sharing Across Network Topologies" White Paper.

• Valley Region HIE has joined a nationwide health information exchange, Big Health Exchange.
• Big Health Exchange doesn't have any central service endpoints; it operates on a peer to peer model.
• New Hope Medical Partners has joined Big Health Exchange and now has access to the desired organizations participating in Valley Region HIE through the Big Health Exchange. New Hope Medical Partners will access these organizations via the "Valley BigHx Responding Gateway" endpoints, which are associated with OrganizationAffiliation5.
• Valley Region HIE retains its internal service endpoints for PDQ (Patient Demographics Query) and XDS (Cross-Enterprise Document Sharing) for its members. Additionally, it has introduced initiating gateway endpoints to enable its members to access the Big Health Exchange and aggregate internal data.
• Async endpoints and their response endpoints show that even though members of Valley HIE utilize central services, they need individual async endpoints to receive responses.

We’ve omitted some details, since they aren’t involved in this Document Access example:

• New Hope’s Responding Gateway and internal details
• Push-style endpoint connection types

This example provides answers to the following questions:

1. Which Valley Region HIE endpoints are listed in the National Directory?
2. Which Valley Region HIE endpoints can be accessed by members of Big Health Exchange?
3. Which Valley Region HIE endpoints are appropriate to use for a specific task at hand?

This example was adapted from section 5.1.8 in the IHE Topologies white paper.

Push-based Referral Use Case

Dr. Suwati from New Hope Medical Partners referred a patient to Dr. Santos at University Health. New Hope Medical Partners is a member of Big Health Exchange, while University Health participates in Valley Region HIE, which in turn is part of Big Health Exchange. Big Health Exchange operates without any central service endpoints, functioning on a peer-to-peer model.

The sequence diagram looks like:

The diagram illustrating the utilization of resources and their interconnections

This example was adapted from section 5.2.2 in the IHE Topologies white paper.

Discover an HIE endpoint via the NDH

Use case: Discovery of SutterHealth TEFCA endpoint

Actors:

• Health Information System (HIS)
• NDH (National Directory of Healthcare Providers & Services)

Preconditions:

• SutterHealth is a known participating organization in the Healthcare Organization.
• SutterHealth is participating in both the TEFCA-QHIN (eHealth Exchange) and CareQuality Health Information Exchange (HIE) networks.

Main Flow:

1. The user (in this case a software agent of system) queries NDH to find the SutterHealth Organization
2. The user queries NDH for the OrganizationAffiliation resource instance with the code for 'HIEResponder' and 'TEFCA-Organization' to find an affiliation related to SutterHealth.
3. NDH returns the OrganizationAffiliation resource instance
4. The endpoint contained in the OrganizationAffiliation resource instance is the SutterHealth TEFCA Endpoint

FHIR resources relationship diagram for the use case above

Associate an organization with an insurance plan that operates without any network.

A State InsurancePlan Entity may contract directly with a provider organization which provides the HealthcareService. A logical Network could be used to link an InsurancePlan and an Organization which provides the HealthcareService for the InsurancePlan via an OrganizationAffiliation.

Relationship use cases

Relationship between networks and participants

An entity, whether it be an organization or a practitioner, might be part of multiple networks. There may be occasions when a specific network becomes unavailable or when a member decides to withdraw from an active network. To manage these potential changes - one originating from the network itself and the other from the participant's side - the recommendation is to ensure that each PractitionerRole or OrganizationAffiliation resource instance only includes a single network.

The PractitionerRole is designated for practitioners, whereas the OrganizationAffiliation is geared towards organizations. Both these resources, PractitionerRole and OrganizationAffiliation, contain a period element. This element signifies the valid timeframe of a network's relationship with its participants. In the event of a change in this relationship, a new instance would be created, encompassing the updated period.

This method allows for the efficient management of transitions, avoiding the creation of a more intricate system that would involve tracking expiration dates across multiple resources and relationships.

See Example

Subscribe to receive real-time notifications when data is created, updated, or deleted on the NDH server

Subscribe to changes in practitioner qualification for providers in the state of Maryland

A change in a practitioner's qualifications doesn't only impact the practitioner, but also any associated organizations and services. By subscribing to the "practitioner-qualification-change" topic, subscribers will receive notifications about these changes.

In this scenario, a subscriber wishes to be alerted whenever a practitioner in Maryland undergoes a qualification change. They also want notifications to include the resource identifier for all affected resources.

Here is the example of the subscription: [Topicbased-Subscription-Practitioner-Qualification-Change]

Bulk export to access large volumes information on demand

Bulk extract of all information for organizations, individuals, and services in the state of Maryland from the NDH

GET [base]/$export?_type=Organization,OrganizationAffiliation,Practitioner,PractitionerRole,HealthcareService,Location,InsurancePlan
&_since=[transactionTime]
&_typeFilter=Organization?address-state=MD,
Organization?type=ntwk&address-state=MD,
OrganizationAffiliation?location.address-state=MD,
OrganizationAffiliation?service.location.address-state=MD,
Practitioner?address-state=MD,
PractitionerRole?location.address-state=MD,
PractitionerRole?service.location.address-state=MD,
PractitionerRole?network.type=ntwk&network.address-state=MD,
HealthcareService?location.address-state=MD,
Location?address-state=MD,
InsurancePlan?plan.coverageArea.address-state=MD,
&_outputFormat=application/fhir+ndjson

Note: Bulk Data Export _typeFilter does not support _include and _revinclude search parameters.

National Directory Scheduled Bulk Data Export

If a local directory needs to retrieve information from the National Directory on a scheduled basis, there are two approaches available.
The first approach is a client-side solution, where a job scheduler script is written on the client side to execute the Bulk Data $export operation. This allows the client to control the export process and retrieve the data as needed.
Alternatively, the second approach is to utilize the National Directory Scheduled Bulk Data $ndhschExport operation, which is a service-side solution available to all registered clients. Once the client has registered with the NDH, they only need to apply the $ndhschExport operation once. From then on, the system automatically exports the data to the specified file storage location based on the defined schedule, making it convenient for the client to retrieve the data.

NdhschExport-operation-flow-diagram

Schedule extracts of specific resources for all organization and individuals in MD weekly

OperationDefinition-NdhschExport

GET [base]/$ndhschExport
?_type=Organization,OrganizationAffiliation,Practitioner,PractitionerRole,HealthcareService,Location,InsurancePlan
&_typeFilter=Organization?address-state=MD,_include=*,revinclude=*
&_outputFormat=application/fhir_ndjson
&_startdate=2023-06-01
&_frequency=weekly
&_account=example-1
&_action=create

</g></svg> <figcaption></figcaption> </figure>

DirectTrust Ecosystem Modeled in NDH

Organizational Structure

1. HISP 1 Organization represents a Health Information Service Provider (HISP). A HISP establishes affiliations with Organizational entities which participate in the DirectTrust network and maintains the DirectTrust Endpoints (e.g., Direct messaging addresses) for those participating Organizations.
2. OrganizationAffiliation represents trust and operational relationships between the HISP (as organization) and the Organization participating in the DirectTrust network (as participatingOrganization).
3. Organization (mailing address included in the directory) acts as the central administrative hub. Multiple Locations (practice addresses in the directory) reference the Organization through managingOrganization, ensuring consistency of administrative oversight across sites and services.
4. Endpoints exposed for Organizations or specific care locations in the Directory are referenced as endpoints from OrganizationAffiliation and Location.
5. Endpoints exposed for Practitioners in the Directory are referenced as endpoints from the PractitionerRole Resource which links Practitioners to Locations and Organizations.
6. Every Endpoint links back to the associated Organization via the managingOrganiztion element of the Endpoint.

Endpoint Distribution

Endpoints (1–6) are distributed across Organizations, Locations, and PractitionerRoles, demonstrating NDH’s capability to register and publish multiple technical contact points:

• Organizational endpoints for administrative communications.
• Location endpoints for site-specific services.
• PractitionerRole endpoints for direct clinical messaging tied to a Practitioner in their role working for a specific Organization.

Locations of Practice

• Locations 2, 3, and 4 represent physical practice sites.
• Each Location references its managingOrganization to indicate administrative responsibility for the DirectTrust endpoints associated with that Location.
• PractitionerRoles reference these Locations to indicate where practitioners deliver care (a common way to search for or isolate the desired communication endpoint).

Practitioner-Organization-Location Linkage

• PractitionerRole 1 and PractitionerRole 2 illustrate NDH’s linkage model
• Each PractitionerRole links a Practitioner (practitioner) to an Organization (organization), one or more Locations (location) and relevant Endpoints (endpoint) for the Practitioner at those locations which are managed by the Organization.
• The Practitioner node represents a specific clinician, potentially working across multiple practice locations for one or more organizations.

Why this matters in DirectTrust

The NDH directory enables the publication of authoritative, interoperable healthcare directory information that supports:

• Trust framework discovery (e.g., HISPs, Organizations, and their endpoints).
• Accurate routing of Direct messages, FHIR API transactions, and other data exchanges.
• Relationship resolution between practitioners, their organizations, and endpoints to be used.
• Federated directories where a single practitioner may operate across multiple sites, with distinct roles and endpoints, while remaining discoverable.
• This model reflects how DirectTrust participants—HISPs, organizations, and providers—can be registered once and reused across multiple contexts, ensuring trusted, consistent, standards-based interoperability through NDH.

–>