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 https://github.com/HL7/fhir-us-ndh/ and changes regularly. See the Directory of published versions

CapabilityStatement: National Directory API Capability Statement

Official URL: http://hl7.org/fhir/us/ndh/CapabilityStatement/national-directory-api-server Version: 1.0.0-ballot
Active as of 2022-11-01 Computable Name: NationalDirectoryApiServerCapabilityStatement

This Section describes the expected capabilities of the NDH Server actor which is responsible for providing responses to the queries submitted by the NDH Requestors. The complete list of FHIR profiles, RESTful operations, and search parameters supported by NDH Servers are defined. NDH Clients have the option of choosing from this list to access necessary data based on their local use cases and other contextual requirements.

Raw OpenAPI-Swagger Definition file | Download


General

Supported FHIR Version: 4.0.1
Supported exchange formats: xml, json

Jump to:


REST Server behavior

National Directory API Server


Resource summary

Resource Search Read Read Version Instance History Resource History Create Update Delete Operations
Endpoint SHALL SHALL SHALL SHALL SHALL
CareTeam SHALL SHALL SHALL SHALL SHALL
HealthcareService SHALL SHALL SHALL SHALL SHALL
InsurancePlan SHALL SHALL SHALL SHALL SHALL
Location SHALL SHALL SHALL SHALL SHALL
Organization SHALL SHALL SHALL SHALL SHALL
OrganizationAffiliation SHALL SHALL SHALL SHALL SHALL
Practitioner SHALL SHALL SHALL SHALL SHALL
PractitionerRole SHALL SHALL SHALL SHALL SHALL
Consent SHALL SHALL SHALL SHALL SHALL
VerificationResult SHALL SHALL SHALL SHALL SHALL
Subscription SHALL SHALL SHALL

Operations:



Endpoint

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  read SHALL

Read the current state of the resource
  vread SHALL

Read the state of a specific version of the resource
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type

Search

Supported Includes: Endpoint:organization

Supported Reverse-Includes: CareTeam:endpoint, HealthcareService:endpoint, InsurancePlan:endpoint, Location:endpoint, Organization:endpoint, OrganizationAffiliation:endpoint, Practitioner:endpoint, PractitionerRole:endpoint

Parameter Name Definition Conformance Type Description
usecase-type EndpointUsecaseTypeSearchParameter SHALL Token

Endpoint usecase type
nonfhir-usecase-type EndpointNonfhirUsecaseTypeSearchParameter SHALL Token

Endpoint nonfhir usecase type
trust-framework-type EndpointTrustFrameworkTypeSearchParameter SHALL Token

Endpoint trust framework type
dynamic-registration-trust-profile EndpointDynamicRegistrationTrustProfileSearchParameter SHALL Token

Endpoint dynamic registration trust profile
access-control-mechanism EndpointAccessControlMechanismSearchParameter SHALL Token

Endpoint access control mechanism
connection-type-version EndpointConnectionTypeVersionSearchParameter SHALL Token

Endpoint connection type version
ihe-connection-type EndpointIheConnectionTypeSearchParameter SHALL Token

Endpoint ihe connection type
verification-status EndpointVerificationStatusSearchParameter SHALL Token

Endpoint verification status
_filter http://hl7.org/fhir/SearchParameter/Resource-filter SHALL Special

supports a more sophisticated grammar for searching
_id _id SHALL Token

Logical id allows to retrive more than one in a single call
_lastUpdated _lastUpdated SHALL Date/DateTime

Allows filtering for only records that have changed since last query.
connection-type connection-type SHALL Token

Connection type
identifier identifier SHALL Token

Endpoint identifier
organization organization SHALL Reference

Organization that manages the Endpoint
status status SHALL Token

Endpoint status


CareTeam

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  read SHALL

Read the current state of the resource
  vread SHALL

Read the state of a specific version of the resource
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type

Search

Supported Includes: CareTeam:location, CareTeam:organization, CareTeam:service

Parameter Name Definition Conformance Type Description
endpoint CareTeamEndpointSearchParameter SHALL Reference

Endpoint of the CareTeam
location CareTeamLocationSearchParameter SHALL Reference

Location of the CareTeam
organization CareTeamOrganizationSearchParameter SHALL Reference

Organization of the CareTeam
service CareTeamServiceSearchParameter SHALL Reference

Service of the CareTeam
name CareTeamNameSearchParameter SHALL String

Name of the CareTeam
verification-status CareTeamVerificationStatusSearchParameter SHALL Token

Verification status of the CareTeam
_filter http://hl7.org/fhir/SearchParameter/Resource-filter SHALL Special

supports a more sophisticated grammar for searching
_id _id SHALL Token

Logical id allows to retrive more than one in a single call
_lastUpdated _lastUpdated SHALL Date/DateTime

Allows filtering for only records that have changed since last query.
category category SHALL Token

Type of team
participant participant SHALL Reference

Who is involved
status status SHALL Token

Status of the CareTeam


HealthcareService

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  read SHALL

Read the current state of the resource
  vread SHALL

Read the state of a specific version of the resource
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type

Search

Supported Includes: HealthcareService:coverage-area, HealthcareService:endpoint, HealthcareService:location, HealthcareService:new-patient-from-network, HealthcareService:organization

Supported Reverse-Includes: CareTeam:service, OrganizationAffiliation:service, PractitionerRole:service

Parameter Name Definition Conformance Type Description
new-patient-from-network HealthcareServiceNewPatientFromNetworkSearchParameter SHALL Reference

New patient from network
eligibility HealthcareServiceEligibilitySearchParameter SHALL Token

Eligibility
new-patient HealthcareServiceNewPatientSearchParameter SHALL Token

New patient
verification-status HealthcareServiceVerificationStatusSearchParameter SHALL Token

Verification status
network HealthcareServiceNetworkSearchParameter SHALL Reference

Network
program-requirement-age-group HealthcareServiceProgramRequirementAgeGroupSearchParameter SHALL Token

Program requirement age group
program-requirement-birthsex HealthcareServiceProgramRequirementBirthsexSearchParameter SHALL Token

Program requirement birthsex
program-requirement-gender-identity HealthcareServiceProgramRequirementGenderIdentitySearchParameter SHALL Token

Program requirement gender identity
program-requirement-employment-status HealthcareServiceProgramRequirementEmploymentStatusSearchParameter SHALL Token

Program requirement employment status
program-requirement-insurance-status HealthcareServiceProgramRequirementInsuranceStatusSearchParameter SHALL Token

Program requirement insurance status
program-requirement-va-status HealthcareServiceProgramRequirementVaStatusSearchParameter SHALL Token

Program requirement va status
program-requirement-preferred-language HealthcareServiceProgramRequirementPreferredLanguageSearchParameter SHALL Token

Program requirement preferred language
social-service-age-group HealthcareServiceSocialServiceAgeGroupSearchParameter SHALL Token

Social service requirement age group
social-service-birthsex HealthcareServiceSocialServiceBirthsexSearchParameter SHALL Token

Social service requirement birthsex
social-service-gender-identity HealthcareServiceSocialServiceGenderIdentitySearchParameter SHALL Token

Social service requirement gender identity
social-service-employment-status HealthcareServiceSocialServiceEmploymentStatusSearchParameter SHALL Token

Social service requirement employment status
social-service-insurance-status HealthcareServiceSocialServiceInsuranceStatusSearchParameter SHALL Token

Social service requirement insurance status
social-service-va-status HealthcareServiceSocialServiceVaStatusSearchParameter SHALL Token

Social service requirement va status
social-service-preferred-language HealthcareServiceSocialServicePreferredLanguageSearchParameter SHALL Token

Social service requirement preferred language
location HealthcareServiceLocationSearchParameter SHALL Reference

The location of the Healthcare Service
organization HealthcareServiceOrganizationSearchParameter SHALL Reference

The organization that provides this Healthcare Service
_filter http://hl7.org/fhir/SearchParameter/Resource-filter SHALL Special

supports a more sophisticated grammar for searching
_id _id SHALL Token

Logical id allows to retrive more than one in a single call
_lastUpdated _lastUpdated SHALL Date/DateTime

Allows filtering for only records that have changed since last query.
active active SHALL Token

Whether this HealthcareService record is in active use
coverage-area coverage-area SHALL Reference

Location service is inteded for/available to
endpoint endpoint SHALL Reference

Technical endpoints providing access to services operated for the location
identifier identifier SHALL Token

External identifiers for this item
name name SHALL String

A portion of the Healthcare service name
program program SHALL Token

One of the Program Names that categorize the service
service-category service-category SHALL Token

Service Category of the Healthcare Service
service-type service-type SHALL Token

The type of service provided by this healthcare service
specialty specialty SHALL Token

Specialties handled by the HealthcareService


InsurancePlan

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  read SHALL

Read the current state of the resource
  vread SHALL

Read the state of a specific version of the resource
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type

Search

Supported Includes: InsurancePlan:administered-by, InsurancePlan:endpoint, InsurancePlan:owned-by, InsurancePlan:coverage-area, InsurancePlan:coverage-network, InsurancePlan:plan-network, InsurancePlan:network

Parameter Name Definition Conformance Type Description
coverage-area InsuranceCoverageAreaSearchParameter SHALL Reference

InsurancePlan coverage area
coverage-benefit-type InsuranceplanCoverageBenefitTypeSearchParameter SHALL Token

InsurancePlan coverage benefit type
coverage-type InsuranceplanCoverageTypeSearchParameter SHALL Token

InsurancePlan coverage type
coverage-network InsuranceplanCoverageNetworkSearchParameter SHALL Reference

InsurancePlan coverage network
network InsuranceplanPlanNetworkSearchParameter SHALL Reference

InsurancePlan network
plan-network InsuranceplanPlanNetworkSearchParameter SHALL Reference

InsurancePlan plan network
plan-type InsuranceplanPlanTypeSearchParameter SHALL Token

InsurancePlan plan type
verification-status InsuranceplanVerificationStatusSearchParameter SHALL Token

Verification status
_filter http://hl7.org/fhir/SearchParameter/Resource-filter SHALL Special

supports a more sophisticated grammar for searching
_id _id SHALL Token

Logical id allows to retrive more than one in a single call
_lastUpdated _lastUpdated SHALL Date/DateTime

Allows filtering for only records that have changed since last query.
address address SHALL String

InsurancePlan contact address
address-city address-city SHALL String

InsurancePlan contact address-city
address-country address-country SHALL String

InsurancePlan contact address-country
address-postalcode address-postalcode SHALL String

InsurancePlan contact address-postalcode
address-state address-state SHALL String

InsurancePlan contact address-state
administered-by administered-by SHALL Reference

InsurancePlan administered by
endpoint endpoint SHALL Reference

InsurancePlan endpoint
identifier identifier SHALL Token

InsurancePlan identifier
name name SHALL String

InsurancePlan name
owned-by owned-by SHALL Reference

InsurancePlan owned by
status status SHALL Token

InsurancePlan status
type type SHALL Token

InsurancePlan type


Location

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  read SHALL

Read the current state of the resource
  vread SHALL

Read the state of a specific version of the resource
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type

Search

Supported Includes: Location:endpoint, Location:new-patient-from-network, Location:organization, Location:partof

Supported Reverse-Includes: CareTeam:location, HealthcareService:coverage-area, HealthcareService:location, InsurancePlan:coverage-area, OrganizationAffiliation:location, PractitionerRole:location

Parameter Name Definition Conformance Type Description
accessibility LocationAccessibilitySearchParameter SHALL Token

Location accessibility
contains LocationContainsSearchParameter SHALL Special

Location contains
new-patient-from-network LocationNewPatientFromNetworkSearchParameter SHALL Reference

Location new patient from network
new-patient LocationNewPatientSearchParameter SHALL Token

Location new patient
verification-status LocationVerificationStatusSearchParameter SHALL Token

Verification status
_filter http://hl7.org/fhir/SearchParameter/Resource-filter SHALL Special

supports a more sophisticated grammar for searching
_id _id SHALL Token

Logical id allows to retrive more than one in a single call
_lastUpdated _lastUpdated SHALL Date/DateTime

Allows filtering for only records that have changed since last query.
address address SHALL String

Location address
address-city address-city SHALL String

Location address-city
address-country address-country SHALL String

Location address-country
address-postalcode address-postalcode SHALL String

Location address-postalcode
address-state address-state SHALL String

Location address-state
address-use address-use SHALL Token

Location address-use
endpoint endpoint SHALL Reference

Location endpoint
identifier identifier SHALL Token

Location identifier
name name SHALL String

Location name
near near SHALL Special

Location position
partof partof SHALL Reference

Location partof
organization organization SHALL Reference

Location organization
type type SHALL Token

Location type


Organization

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  read SHALL

Read the current state of the resource
  vread SHALL

Read the state of a specific version of the resource
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type

Search

Supported Includes: Organization:endpoint, Organization:partof

Supported Reverse-Includes: CareTeam:organization, Endpoint:organization, HealthcareService:organization, HealthcareService:new-patient-from-network, HealthcareService:network, InsurancePlan:administered-by, InsurancePlan:owned-by, InsurancePlan:coverage-network, InsurancePlan:plan-network, Location:organization, Location:new-patient-from-network, OrganizationAffiliation:network, OrganizationAffiliation:participating-organization, OrganizationAffiliation:primary-organization, Practitioner:qualification-issuer, PractitionerRole:organization, PractitionerRole:network, PractitionerRole:new-patient-from-network

Parameter Name Definition Conformance Type Description
coverage-area NetworkCoverageAreaSearchParameter SHALL Reference

network organization type is needed for searching network coverage area
verification-status OrganizationVerificationStatusSearchParameter SHALL Token

Verification status
_filter http://hl7.org/fhir/SearchParameter/Resource-filter SHALL Special

supports a more sophisticated grammar for searching
_id _id SHALL Token

Logical id allows to retrive more than one in a single call
_lastUpdated _lastUpdated SHALL Date/DateTime

Allows filtering for only records that have changed since last query.
active active SHALL Token

Organization active
address address SHALL String

Organization address
address-city address-city SHALL String

Organization address-city
address-country address-country SHALL String

Organization address-country
address-postalcode address-postalcode SHALL String

Organization address-postalcode
address-state address-state SHALL String

Organization address-state
address-use address-use SHALL Token

Organization address-use
endpoint endpoint SHALL Reference

Organization endpoint
identifier identifier SHALL Token

Organization identifier
name name SHALL String

Organization name
partof partof SHALL Reference

Organization partof
type type SHALL Token

Organization type


OrganizationAffiliation

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type
  read SHALL

Read the current state of the resource
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  vread SHALL

Read the state of specific version of the resource

Search

Supported Includes: OrganizationAffiliation:network, OrganizationAffiliation:participating-organization, OrganizationAffiliation:primary-organization

Parameter Name Definition Conformance Type Description
location OrganizationAffiliationLocationSearchParameter SHALL Reference

OrganizationAffiliation location
participating-organization OrganizationAffiliationParticipatingOrganizationSearchParameter SHALL Reference

OrganizationAffiliation participating-organization
primary-organization OrganizationAffiliationPrimaryOrganizationSearchParameter SHALL Reference

OrganizationAffiliation primary-organization
verification-status OrganizationAffiliationVerificationStatusSearchParameter SHALL Token

Verification status
_filter http://hl7.org/fhir/SearchParameter/Resource-filter SHALL Special

supports a more sophisticated grammar for searching
_id _id SHALL Token

Logical id allows to retrive more than one in a single call
_lastUpdated _lastUpdated SHALL Date/DateTime

Allows filtering for only records that have changed since last query.
endpoint endpoint SHALL Reference

OrganizationAffiliation endpoint
identifier identifier SHALL Token

OrganizationAffiliation identifier
network network SHALL Reference

OrganizationAffiliation network
role role SHALL Token

OrganizationAffiliation role
service service SHALL Reference

OrganizationAffiliation service
specialty specialty SHALL Token

OrganizationAffiliation specialty


Practitioner

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  read SHALL

Read the current state of the resource
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  vread SHALL

Read the state of specific version of the resource
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type

Search

Supported Includes: Practitioner:endpoint, Practitioner:qualification-issuer

Supported Reverse-Includes: PractitionerRole:practitioner

Parameter Name Definition Conformance Type Description
endpoint PractitionerEndpointSearchParameter SHALL Reference

Practitioner endpoint
qualification-issuer PractitionerQualificationIssuerSearchParameter SHALL Reference

Practitioner qualification issuer
qualification-code PractitionerQualificationCodeSearchParameter SHALL Token

Practitioner qualification code
verification-status PractitionerVerificationStatusSearchParameter SHALL Token

Verification status
_filter http://hl7.org/fhir/SearchParameter/Resource-filter SHALL Special

supports a more sophisticated grammar for searching
_id _id SHALL Token

Logical id allows to retrive more than one in a single call
_lastUpdated _lastUpdated SHALL Date/DateTime

Allows filtering for only records that have changed since last query.
active active SHALL Token

Whether this practitioner's record is in active use
name name SHALL String

A portion of either family or given name of the practitioner
gender gender SHALL Token

Practitioner gender
identifier identifier SHALL Token

A practitioner's Identifier


PractitionerRole

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  read SHALL

Read the current state of the resource
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  vread SHALL

Read the state of specific version of the resource
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type

Search

Supported Includes: PractitionerRole:endpoint, PractitionerRole:location, PractitionerRole:network, PractitionerRole:new-patient-from-network, PractitionerRole:organization, PractitionerRole:practitioner, PractitionerRole:service

Parameter Name Definition Conformance Type Description
network PractitionerroleNetworkSearchParameter SHALL Reference

PractitionerRole network
new-patient PractitionerroleNewPatientSearchParameter SHALL Token

PractitionerRole new-patient
new-patient-from-network PractitionerroleNewPatientFromNetworkSearchParameter SHALL Reference

PractitionerRole new-patient from network
location PractitionerroleLocationSearchParameter SHALL Reference

One of the locations at which this practitioner provides care
organization PractitionerroleOrganizationSearchParameter SHALL Reference

The identity of the organization the practitioner represents / acts on behalf of
verification-status PractitionerroleVerificationStatusSearchParameter SHALL Token

Verification status
_filter http://hl7.org/fhir/SearchParameter/Resource-filter SHALL Special

supports a more sophisticated grammar for searching
_id _id SHALL Token

Logical id allows to retrive more than one in a single call
_lastUpdated _lastUpdated SHALL Date/DateTime

Allows filtering for only records that have changed since last query.
active active SHALL Token

Whether this practitioner's record is in active use
endpoint endpoint SHALL Reference

Technical endpoints providing access to services operated for the practitioner with this role
identifier identifier SHALL Token

A practitioner's Identifier
practitioner practitioner SHALL Reference

Practitioner that is able to provide the defined services for the organization
role role SHALL Token

The practitioner can perform this role at for the organization
service service SHALL Reference

The list of healthcare services that this worker provides for this role's Organization/Location
specialty specialty SHALL Token

The practitioner has this specialty at an organization


Consent

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  read SHALL

Read the current state of the resource
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  vread SHALL

Read the state of specific version of the resource
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type

Search

Parameter Name Definition Conformance Type Description
action action SHALL Token

Actions controlled by this rule
actor actor SHALL Reference

Resource for the actor or group - by role
category category SHALL Token

Classification of the consent statement - for indexing/retrieval
purpose purpose SHALL Token

Context of activities covered by this rule
security-label security-label SHALL Token

Security Labels that define affected resources
scope scope SHALL Token

Which of the four areas this resource covers - extensible
status status SHALL Token

draft; proposed active rejected inactive or entered-in-error


VerificationResult

Supported Profile(s):

Behavior

Versioning support: Versioned

Reference policy: Literal References, Local References Only

Interactions

Name Conformance Description
  read SHALL

Read the current state of the resource
  search-type SHALL

Search all resources of the specified type based on some filter criteria.
  vread SHALL

Read the state of specific version of the resource
  history-instance SHALL

Retrieve the history of the resource
  history-type SHALL

Retrieve the history of the resource type

Search

Supported Includes: VerificationResult:target, VerificationResult:attestation-who

Parameter Name Definition Conformance Type Description
attestation-who VerificationResultAttestationWhoSearchParameter SHALL Reference

VerificationResult attestation who
primarysource-validation-status VerificationResultPrimarysourceValidationStatusSearchParameter SHALL Token

VerificationResult primarysource validation-status
primarysource-type VerificationResultPrimarysourceTypeSearchParameter SHALL Token

VerificationResult primarysource type
status VerificationResultStatusSearchParameter SHALL Token

VerificationResult status
target VerificationResultTargetSearchParameter SHALL Reference

VerificationResult target
_filter http://hl7.org/fhir/SearchParameter/Resource-filter SHALL Special

supports a more sophisticated grammar for searching
_id _id SHALL Token

Logical id allows to retrive more than one in a single call
_lastUpdated _lastUpdated SHALL Date/DateTime

Allows filtering for only records that have changed since last query.


Subscription

Supported Profile(s):

Interactions

Name Conformance Description
  read SHALL

Read Topic
  create SHALL

Create Topic
  update SHALL

Update Topic