National Directory of Healthcare Providers & Services (NDH) Implementation Guide
1.0.0-ballot - ballot United States of America flag

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 1.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of 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).

National Directory Use Case ActorsGUI for ConsumerConsumers to search:providers' accessibility information(specialty, office hours, taking patients,languages spoken, etc.) relationship between providerand insurance plan(in-network, out-of-network, etc.) facility's accessibility information(location, hours, services, etc.) community organizations'accessibility information(location, hours, services, etc.) Coordination ActorCare coordinatorBenefits coordinatorRefferal coordinatorDischarge plannerProviders and Payers ActorPlan Network management (enrollment&contracting)Plan Claims managementAccountable Care Organization (ACO)Value based planManaged care plan OrganizationCredentialingCompliance/auditing staffSystem or Services (Patient attribution service ect.)Developer ActorApplication developerEHR developerNationalDirectoryA centralized data hubfor healthcare directory information,offering accurate and verified data,along with FHIR APIs for accessing the data.Providing a single source of truth forhealth plan networks,provider directories,and facility directories. Supporting the following use cases:Locating providers,Comparing health plan networks,Coordinating facility care,Exchanging health providers information,Reporting public health data.States HIE/HIN ActorIncorporate regional and national HINsto facilitate interoperability

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.

Discovery Healthcare Providers & Services Information FlowInquirer: OrganizationIndividualor SystemNational Directory ofHealthcare Providers& Services"Fully qualified query""Records returned (0..*)"

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:

Query Query Name Query Description Examples
1 Find Individual Request a list of individuals by specifying one or more individual attributes Find a practitioner by Name
GET [base]/Practitioner?name=Hans Solo
2 Find Unique Individual Request a specific individual by specifying an individual unique reference ID Find a practitioner by NPI
GET [base]/Practitioner?identifier=|1003357849
3 Find Organization Request a list of organizations and relationships to other organizations by specifying one or more organization attributes GET [base]/Organization?identifier=|1518575422&_revinclude=OrganizationAffiliation:participating-organization
4 Find Unique Organization Request a specific organization and relationships to other organizations by specifying an organization unique reference ID GET [base]/OrganizationAffiliation?primary-organization.identifier=|1518575422&_include=OrganizationAffiliation:primary-organization&include=OrganizationAffiliation:participating-organization
5 Find Organizations for Unique Individual Request a specific individual and related organizations by specifying an individual unique reference ID and one or more attributes of organizations; organizations and relationships to the specified individual are returned when the organization matches the organization attributes and has a relationship to the individual specified; attributes on the relationship between the individual and organization can also be specified in this query and further constrain which organizations and relationships are returned 1. Since a practitioner could provide the service to multiple organizations. Those organizations are not limited to one hospital system.
GET [base]/Practitioner/?identifier=|1003357849&_revinclude=PractitionerRole:practitioner

2. A practitioner in the city of Boston related to multiple organization
GET [base]/PractionerRole?practitioner.identifier=|1003357849&organization.address-city=Boston&_include=PractitionerRole:practitioner&include=PractitionerRole:organization
6 Find Individuals for Unique Organization Request a specific organization and related individuals by specifying an organization unique reference ID and one or more attributes of individuals; individuals and relationships to the specified organization are returned when the individual matches the individual attributes and has a relationship to the organization specified; attributes on the relationship between the individual and organization can also be specified in this query and further constrain which individuals and relationships are returned GET [base]/PractitionerRole?organization.identifiery=|1518575422&_include=PractitionerRole:practitioner
7 Find Individuals and Organizations Request a list of individuals, organizations and relationships between (individuals/organization or organization/organization) based on attributes of individuals, organizations and individual/organization relationships; response includes all objects (whether individual, organization or relationship) where the individuals match all of the individual attributes specified, the organizations match all of the organization attributes and where a relationship exists between each individual and one or more organizations returned. In the event the query includes one or more attributes regarding the relationship, then each relationship returned must match all the attributes specified; for each organization returned, all its relationships, as parent or child, with other organizations are returned 1. Practitioners and associated Organizations
GET [base]/PractitionerRole?practitioner.address-state=FL&_include=PractionerRole:practitioner&_include=PractitionerRole:organization

2. Organizations with Organizations
GET [base]/OrganizationAffiliation?organization.address-state=FL&_include=OrganizationAffiliation:primary-organization&_include=OrganizationAffiliation:participant-organization

3. Find all providers have relationship in the state of CT
GET [base]/PractitionerRole/?location.address-state=CT&include=*_revinclude=*

4. Query all Endocrinology, Diabetes & Metabolism Physician in the city of Bridgeport, CT accept new patient
GET [base]/PractitionerRole/?specialty=|207RE0101X&new-patient=newpt&location.address-city=Bridgeport&location.address-state=CT&_include=*&_revinclude=*

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.

Individual seeks orthopedic surgeon at Hartford OrthopedicsProceedyesIs part of Acme of CT network HMO?noIdentify Hartford Orthopedics Group as providerEvaluate Location 1 criteriaMatches needsDoes not matchSelect Location 1ProceedyesAccepting new patients?noFinalize Location 1SuitableCheck Location 1 service hoursNot suitableSelect Location 2ProceedyesAccepting new patients?noFinalize Location 2SuitableCheck Location 2 service hoursNot suitableMatches needsEvaluate Location 2 criteriaDoes not match

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.

PractitionerRolePractitionerOrganizationHartford Orthopedics GroupNetworkAcme of CT networkInsurancePlan \HMO insuranceplanLocation 1Location 2practitionerorganizationnetworklocationlocationnetwork

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
Organizationpayer1EndpointMTLS EndpointOrganizationpayer2EndpointUDAP Well Known EndpointOrganizationpayer3EndpointMTLS EndpointEndpointUDAP Well Known Endpointendpointendpointendpointendpoint

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.

PractitionerPractitionerRolethe relationships among a practitioner,organization, network ...Organizationwhere the practitioner worksOrganizationpayerLocationwhere the practitionerprovide servicesNetworkEndpointProvider endpointEndpointProvider endpointEndpointPayer endpointEndpointProvider endpointat the given locationInsurancePlanpractitionerorganizationendpointlocationendpointnetworkpartOf:endpointnetwork

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
PractitionerPractitionerRolepractitioner has a role at hospital 1PractitionerRolepractitioner has a role at hospital 2Organizationhospital 1Organizationhospital 2practitionerpractitionerorganizationorganization

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.

A practitioner practices in two locations one location is in-network and another location is out-of-networkPractitionerPractitionerRolethe relationships among a practitionerorganization, network, location, endpointOrganizationwhere the practitioner worksOrganizationpayer organizationPractitionerRolethe relationships among a practitionerorganization, location, endpointLocationthe first location wherepractitioner provide serviceswithin the insurance coverage areaof the networkLocationthe second location wherepractitioner provide servicesoutside the insurance coverage areaLocationthe insurance coverage areaNetworkEndpointProvider endpointEndpointProvider endpointEndpointPayer endpointEndpointProvider endpointat the given locationEndpointProvider endpointEndpointProvider endpointat the given locationInsurancePlanpractitionerorganizationendpointlocationendpointnetworkendpointnetworkpartOflocationpractitionerorganizationlocationendpointendpoint

Use cases for supporting IHE 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 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.

This example provides answers to the following questions:

  1. It id possible to locate the endpoint in the National Directory.
  2. The endpoints can be accessed by members of the organization.
  3. It is appropriate to use the endpoint for the task at hand.

More infromation in the White Paper

HIE Access Multi-Level-Community:Organizationname = "Big Health Exchange"OrgID = 7.8.9:Organizationname = "New HopeMedical Partners"New Hope BigHx External Initiating Gateway : Endpoint(s)ihe-specific-connection-type =XCPD-InitGateway-PatientDiscovery-AsyncResponse,XCA-InitGateway-Query-AsyncResponse,XCA-InitGateway-Retrieve-AsyncResponseorgAff4:OrganizationAffiliationcode = “HIEResponder”:Organizationname = "Valley Region HIE"OrgID = = 1.2.3orgAff5:OrganizationAffiliationcode = “HIEResponder”Valley BigHx Responding Gateway : Endpoint(s)ihe-specific-connection-type =XCPD-RespGateway-PatientDiscovery,XCPD-RespGateway-PatientDiscovery-Async,XCA-RespGateway-Query,XCA-RespGateway-Retrieve,XCA-RespGateway-Query-Async,XCA-RespGateway-Retrieve-AsyncValley BigHx External Initiating Gateway : Endpoint(s)ihe-specific-connection-type =XCPD-InitGateway-PatientDiscovery-AsyncResponse,XCA-InitGateway-Query-AsyncResponse,XCA-InitGateway-Retrieve-AsyncResponseValley BigHx Internal Initiating Gateway : Endpoint(s)ihe-specific-connection-type =XCPD-RespGateway-PatientDiscovery,XCPD-RespGateway-PatientDiscovery-Async,XCA-InitGateway-Query,XCA-InitGateway-Retrieve,XCA-InitGateway-Query-Async,XCA-InitGateway-Retrieve-AsyncValley HIE Centralized Services : Endpoint(s)ihe-specific-connection-type =PDQ-Supplier-Query,XDS-Registry-Query,XDS-Registry-Query-Async,XDS-Repository-Retrieve,XDS-Repository-Retrieve-Async,XDS-OnDemandSource-Retrieve,XDS-OnDemandSource-Retrieve-Async:Organizationname = "University Health"alias = "OU Health System","OU Health"OrgID = = "Urgent Health"OrgID = = “HIEResponder”orgAff2:OrganizationAffiliationcode = “HIEInitiator”,“DocShare-federate-int”,“DocShare-federate-ext”orgAff3:OrganizationAffiliationcode = “HIEInitiator”,“DocShare-federate-int”,“DocShare-federate-ext”orgAff6:OrganizationAffiliationcode = “HIEResponder”:Endpointihe-specific-connection-type =XDS-Consumer-Query-AsyncResponse,XDS-Consumer-Retrieve-AsyncResponse:Endpointihe-specific-connection-type =XDS-Consumer-Query-AsyncResponse,XDS-Consumer-Retrieve-AsyncResponseparticipatingOrganizationorganizationparticipatingOrganizationorganizationparticipatingOrganizationorganizationparticipatingOrganizationorganizationparticipatingOrganizationorganizationparticipatingOrganizationorganization

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:

Push-based ReferralNew Hope Medical Partners is a participant of Big Health ExchangeUniversity Health is a participant of Valley Region HIEValley Region HIE is a participant of Big Health ExchangeBig Health Exchange does not have any central service endpoints; it is peer to peerDr. Suwatiat New Hope Medical PartnersDr. Suwatiat New Hope Medical PartnersNew Hope Medical Partners'EHRNew Hope Medical Partners'EHRBig Health ExchangeDirectoryBig Health ExchangeDirectoryValley Region XCDRCross-CommunityDocument Reliable InterchangeValley Region XCDRCross-CommunityDocument Reliable InterchangeUniversity Health XDRCross-EnterpriseDocument Reliable InterchangeUniversity Health XDRCross-EnterpriseDocument Reliable InterchangeDr. Santosat University HealthDr. Santosat University Health"Refer Patient to Dr. Santos@University Health"Search Orgs for University HealthOrg Practitioners for Dr. SantosReturn Practitioner ResourceSearch for Relationship betweenDr. Santos and University HealthReturn PractitionerRole ResourceDr. Santos practices at University Health. Need an endpoint.Search for OrganizationAffiliationwhere University Healthis participatingOrganization: Return OrganizationAffiliation6 ResourcesUniversity Health is a Responder for Valley Region HIE.Is New Hope Medical Partners an Initiator?Search for OrganizationAffiliationwhere Valley Region HIE is organizationReturn OrganizationAffiliation6 ResourcesNot a member. Valley Region HIE also federates.Is there access to Valley Region HIE?Search for OrganizationAffiliationwhere Valley Region HIE is participatingOrganizationReturn OrganizationAffiliation5 ResourcesSearch for OrganiztionAffiliationwhere Big Health Exchange is organizationReturn OrganizationAffliation4 ResourcesNew Hope can Initiate in Big Health Exchange,and Valley Region Responds.Transmit Referral. HCID=1.2.3; intendedRecipient=dr.santos@universityhealth.orgMessage destined for this community.Search for PractitionerRolewith telecom = dr.santos@universityhealth.orgReturn ResourceMessage should go to University Health.Forward messageMessage addressed to Dr. Santos.Deliver messageReturn successReturn success

The diagram illustrating the utilization of resources and their interconnections

:Organizationname = "Big Health Exchange"OrgID = 7.8.9:Organizationname = "New HopeMedical Partners"orgAff4:OrganizationAffiliationcode = “HIEInitiator”:Organizationname = "Valley Region HIE"OrgID = = 1.2.3orgAff5:OrganizationAffiliationcode = “HIEResponder”Valley BigHx Responding Gateway : Endpoint(s)connectionType = "XCDR-RespGateway-DocProvide":Organizationname = "University Health"OrgID = = "Urgent Health"OrgID = = “HIEResponder”orgAff2:OrganizationAffiliationcode = “HIEInitiator”,“DocShare-federate-int”,“DocShare-federate-ext”orgAff3:OrganizationAffiliationcode = “HIEInitiator”,“DocShare-federate-int”,“DocShare-federate-ext”orgAff6:OrganizationAffiliationcode = “HIEResponder”:EndpointconnectionType = "XDR-Recipient-ProvideReg"Practitionername = "Dr. Santos"PractitionerRoletelecom.system = emailtelecom.value = ""specialty = "Neurology"participatingOrganizationorganizationparticipatingOrganizationorganizationparticipatingOrganizationorganizationparticipatingOrganizationorganizationparticipatingOrganizationorganizationparticipatingOrganizationorganizationorganizationpractitioner

Discovery a HIE endpoint via the NDH

Use case: Discovery of SutterHealth TEFCA endpoint


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


  • 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

TEFCA - CareQuality - eHealth ExchangeOrganization/eHealth Exchange(a QHIN)OrgID = 1.3.4Endpoint/SutterHealthTefcaEndpointaddress = = 2.4.1 Notes: "HIEs could have ownEndpoinhts for central,services, e.g.Record Locator Service(RLS)"Endpoint/SutterHealthCarequalityEndpointaddress = = = = “HIEResponder”, Notes: "IHE prfiled - means a QHIN in TEFCAparticipants can hit this Endpoint"OrganizationAffiliation/OrgAff2code = HIEInitiator,DocShare-federate-in,DocShare-federate-ext Notes: "HIE/HIO, a QHIN in TEFCA"Organization/A Healthcare OrganizationOrgID = 1.2.8HCID = 1.2.8OrganizationAffiliation/OrgAff3code = HIEInitiator,DocShare-federate-in,DocShare-federate-ext Notes: "HIE/HIO, TEFCA-QHIN"OrganizationAffiliation/OrgAff4code = “HIEResponder” Notes:"IHE prfiled - means other Carequalityparticipants can hit this Endpoint"OrganizationAffiliation/OrgAff5code = “HIEInitiator” Notes: "TEFCA-Participant,Carequality-Connection,the Healthecare Organization-Instance etc."participatingOrganizationorganizationendpointorganizationparticipatingOrganizationparticipatingOrganizationorganizationparticipatingOrganizationorganizationendpointorganizationparticipatingOrganization

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.

OrganizationAffiliation OrganizationAffiliation/OganizationA(StatePayerEntityInsurancePlan hasa direct contract with an Oganization)InsurancePlan InsurancePlan/StatePayerEntityInsurancePlan.type = MedicaidNetwork Network/LogicalNetworkOrganization Organization/OrganizationA(OrganizationA has a direct contractwith a state payer insurance plan)HealthcareService HealthcareService/OrganizationA(OrganizationA has a direct contract withinsurancePlan to provide service)networknetworkorganizationhealthcareService

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

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.


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


GET [base]/$ndhschExport