Page tree
Skip to end of metadata
Go to start of metadata

Committee Approval Date:


Publishing Lead:

Robert Dieterle

Contributing or Reviewing Work Groups:

Patient Administration (approved on the 11/9/2022 PA WG call)

FHIR Development Project Insight ID:


Scope of coverage:

The scope of this IG is to:

  • combine the existing National Directory Query, Exchange, and Attestation IG into one IG
  • localize the Validated Healthcare Directory (VhDir) IG to the US Realm, update it with lessons learned when the PDex Plan Net IG was created, and expand the support for FHIR endpoints to include metadata identified by the FHIR at Scale Taskforce (FAST) Directory Tiger Team and input from the HL7 community and the relevant workgroups.  
  • define standards for the attestation and validation of information contributed to the National Directory. This information will include personal/professional demographics, organizational demographics, relationships between individuals and organizations, relationships between organizations, and electronic endpoint metadata.
  • support creators and maintainers of both a national validated directory and federated directories that wish to use information available from the national validated directory and provide standard APIs for access to their information. 

Content location: (proposed)

Proposed IG Title:

National Directory for Healthcare

Proposed IG realm and code:

US Realm


FHIR Core version(s):


Maintenance Plan:

FAST Accelerator will maintain the IG in conjunction with the Patient Administration WG

Short Description:

Standard for the population, verification and exchange of Health and Social Care Directory information between a Validated National Directory and local directories (primarily for workflow integration).  This applies to individual demographics, organizational demographics, relationship between individuals and organizations, services provided, and electronic endpoint metadata

Long Description:

Standard for the population, verification and exchange of Health and Social Care Directory information between a Validated National Directory and local directories (primarily for workflow integration).  This applies to individual demographics, organizational demographics, relationship between individuals and organizations, services provided, and electronic endpoint metadata.  The implementation guide defines RESTful APIs for:

1) contributing and attesting to healthcare and social services personal, organization, service and relationship information

Attestation describes the process by which authorized entities submit information about themselves, their roles, their relationships, etc. for inclusion in a health and social care directory.
Guidance in this section is primarily intended to describe expectations for implementers using a FHIR API to manage attestation. An implementer’s unique implementation context, including local business needs, applicable laws/regulations/policies, usability considerations, etc. will determine an implementer’s approach to many of the attestation considerations. 
This guide covers multiple attestation scenarios:

a) Individual service provider attesting to their information
b) Authorized representative attesting to an individual provider’s information
c) Authorized representative attesting to an organization’s information
d) Authorized representative attesting to a payer organization’s information
e) Submission of attested data by an authorized intermediary (e.g., another system that maintains attested data)
f) Each of these scenarios may encompass different sets of “permitted” data. For example, an individual provider attesting to their own information may not have the right to also attest to information about an organization for which they work. 

2) verifying key elements against primary sources or managing mutual attestation for relationships

Validation is critical for ensuring that users of a national directory can rely upon the data in the directory. Validation can refer to separate but related processes: validation of FHIR resources (e.g., checking consistency w/data type, required elements are present, references to existing resources are correct, codes are from appropriate value set etc.), and validation of data against a primary source (e.g., verifying an address using Post Office records). 
This section of the guide is intended to be used by implementers to determine how primary source validation occurs operationally, based in part on the capabilities of the primary sources used for validation. For example, a primary source may already offer a mechanism like an API for validating content against its records. In other cases, an implementer may want to define an API that the primary source can access to push and/or pull content related to validation. Implementers may also consider less technical approaches, such as manual validation, or more stringent requirements, such as mailing a postcard to confirm an address.

3) exchanging attested/verified information between a National Directory and existing federated directories that are integrated into local workflow.

Exchange defines the flow of information from a central source of validated health and social care directory data to local workflow environments. The national validated directory functions as a “source of truth” for a broad set of health and social care directory information (e.g., provider, payer, service providers, endpoint data) available to support local business needs and use cases. A local environment could readily obtain all or a subset of the data it needed from the national directory and have confidence that the information was accurate (by requesting the validation information for specific data elements). If necessary, a federated directory could add data sourced and/or maintained locally. For example, a local directory could add information regarding a provider's work history, liability insurance coverage, or military experience. 
Information expected to be exchanged includes the following:

a) Provider information (Practitioner, PractitionerRole)
b) Organization information (Organization, Location, OrganizationAffiliation)
c) Services (HealthcareService)
d) Payer information (Network, InsurancePlan) (may be optional)
e) Electronic exchange information (Endpoint and required extensions)

4) providing query standards for the federated workflow directory APIs

The primary focus of this section of the implementation guide is to define RESTful APIs to be implemented by local workflow directories that have information from the Validated National Directory. The query and response standards are intended to be utilized by applications that need access to directory information to perform their functions.  In particular, the API definitions will support the ability to identify specific electronic endpoints for the interoperable exchange of information between and within healthcare and social care related entities.
This section will describe the required search parameters and responses for conformant endpoint query implementations and may include any of the information defined in the exchange portion of the IG.

Involved Parties:

Centers for Medicare and Medicaid Services (CMS), Office of the National Coordinator (ONC)

Expected implementations:


Direct Trust







State Healthcare Directories (e.g., MIHIN)

Content sources:

Work from the ONC and FHA (Federal Health Architecture) collaboration that produced the HL7 Validated Healthcare Directory IG (VhDir) and the derivative work HL7 PDex Plan Net

NPPES (National Plan and Provider Enumeration Systems), PECOS (Medicate Provider Enrollment Chain and Ownership System) 

ONC FAST National Directory solution document

Example Scenarios:

1) Standards for the contribution/attestation of personal, organizational, and relationship information including services provided

2) Standards for the contribution/attestation of electronic endpoint metadata (including the use case(s) supported by the endpoint)

3) Standards to query or receive information from primary sources (e.g., post office, license boards, medical schools, endpoint sources) for validation of attested information

4) Request all directory information (e.g., providers, relationships, endpoints) for specific scope of use (e.g., for a State)

5) Request updates for a specific scope of information (e.g., any changes in directory information for a specific State)

6) Request validation information for the information being exchanged between the national directory and the federated directory (e.g., attestation and validation for a provider's qualifications)

7) Request the FHIR endpoint for a provider organization that supports appointment scheduling.

8) Request the Direct endpoint for a provider organization that supports receipt of a CCDA

9) Request the FHIR endpoint for a payer organization that supports payer to payer exchange of USCDI data and return the associated trust framework, and public certificates for a mutual TLS exchange. 

10) Request all endpoints that support referral exchanges for a specific organization

11) Request information on a specific provider and the endpoints for all associated organizations. 

12) Return policies associated with organizational endpoints (e.g., trust framework)

IG Relationships:

This IG depends on profiles defined in:

1) US Core IGs for R 4

2) Bulk Data IG V2.0

3) Smart Framework V2.0

4) UDAP V1.0

5) Subscription Backport


Input IGs (Exchange, Query, and Attestation) were balloted in the September 2022 ballot cycle

FMG Notes

FMG approved on 2022-11-09 call: 2022-11-09 FMG Agenda/Minutes