National Directory of Healthcare Providers & Services (NDH) Implementation Guide
2.0.0-ballot - STU 2 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 2.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: NDH Update Server Capability Statement

Official URL: http://hl7.org/fhir/us/ndh/CapabilityStatement/ndh-update-server Version: 2.0.0-ballot
Standards status: Trial-use Maturity Level: 3 Computable Name: NdhUpdateCapabilityStatement
Other Identifiers: OID:2.16.840.1.113883.4.642.40.43.13.3

The NDH Update Server CapabilityStatement defines the requirements for a server that accepts new and corrected directory data from authorized update requesters through the FHIR API. Query and retrieval of published directory data is defined by the NDH Server CapabilityStatement.

Raw OpenAPI-Swagger Definition file | Download

Language: en

Profile: CapabilityStatement

NDH Update Server Capability Statement

  • Implementation Guide Version: 2.0.0-ballot
  • FHIR Version: 4.0.1
  • Supported Formats: xml, json
  • Supported Patch Formats: application/json-patch+json
  • Published on: 2026-11-10
  • Published by: HL7 International / Patient Administration

Note to Implementers: FHIR Capabilities

Any FHIR capability may be 'allowed' by the system unless explicitly marked as 'SHALL NOT'. A few items are marked as MAY in the Implementation Guide to highlight their potential relevance to the use case.

FHIR RESTful Capabilities

Mode: server

Update requesters submit resources conforming to the NDH profiles. The NDH Update Server validates each submission and returns an OperationOutcome describing each problem when a submission is not valid. Update requesters identify the records they maintain by business identifier, using conditional update to replace a record and conditional patch (PATCH [base]/[type]?identifier=[system]|[value]) to change individual elements. The NDH Update Server SHOULD support ETag and If-Match for collision handling. Records are deactivated rather than deleted: active set to false, period.end recorded on PractitionerRole and OrganizationAffiliation, or status set to inactive (Location), off (Endpoint), or retired (InsurancePlan). The delete interaction is not supported. VerificationResult and Provenance are populated by the directory; update requesters are not required to write them.

Security

The NDH Update Server SHALL meet the security conformance requirements for NDH servers, SHALL authenticate each update requester, and SHALL authorize each write. Identity proofing, record ownership, adjudication of conflicting submissions, and publication of submitted data to the NDH Server are determined by the directory operator.

Summary of System-wide Interactions
  • SHOULD support the transactioninteraction described as follows:

    Submit interdependent resources as one atomic transaction Bundle.

  • MAY support the batchinteraction described as follows:

    Submit independent resources as a batch Bundle.

Capabilities by Resource/Profile

Summary

The summary table lists the resources that are part of this configuration, and for each resource it lists:

  • The relevant profiles (if any)
  • The interactions supported by each resource (Read, Search, Update, and Create, are always shown, while VRead, Patch, Delete, History on Instance, or History on Type are only present if at least one of the resources has support for them.
  • The required, recommended, and some optional search parameters (if any).
  • The linked resources enabled for _include
  • The other resources enabled for _revinclude
  • The operations on the resource (if any)
Resource TypeProfileRSUPCSearches_include_revincludeOperations
EndpointSupported Profiles
  NDH Endpoint Profile
YYYYYidentifier
HealthcareServiceSupported Profiles
  NDH HealthcareService Profile
YYYYYidentifier
InsurancePlanSupported Profiles
  NDH InsurancePlan Profile
YYYYYidentifier
LocationSupported Profiles
  NDH Location Profile
YYYYYidentifier
OrganizationSupported Profiles
  NDH Organization Profile
  NDH Network Profile
YYYYYidentifier
OrganizationAffiliationSupported Profiles
  NDH OrganizationAffiliation Profile
YYYYYidentifier
PractitionerSupported Profiles
  NDH Practitioner Profile
YYYYYidentifier
PractitionerRoleSupported Profiles
  NDH PractitionerRole
YYYYYidentifier
GroupSupported Profiles
  NDH Group
YYYYYidentifier

Core FHIR Resource
Endpoint
Reference Policy
literal, local
Interaction summary
  • SHALL support
    update

    Update an existing resource by its id or by business identifier using conditional update

    read

    Read the current state of the resource

    search-type

    Search by business identifier to locate an existing resource

  • SHOULD support
    create

    Create a new resource with a server assigned id

    patch

    Change individual elements of an existing resource by its id or by business identifier using conditional patch

Supported Profiles

NDH Endpoint Profile

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

Business identifier used to select the record for conditional update

 
Core FHIR Resource
HealthcareService
Reference Policy
literal, local
Interaction summary
  • SHALL support
    update

    Update an existing resource by its id or by business identifier using conditional update

    read

    Read the current state of the resource

    search-type

    Search by business identifier to locate an existing resource

  • SHOULD support
    create

    Create a new resource with a server assigned id

    patch

    Change individual elements of an existing resource by its id or by business identifier using conditional patch

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

Business identifier used to select the record for conditional update

 
Core FHIR Resource
InsurancePlan
Reference Policy
literal, local
Interaction summary
  • SHOULD support
    update

    Update an existing resource by its id or by business identifier using conditional update

    create

    Create a new resource with a server assigned id

    patch

    Change individual elements of an existing resource by its id or by business identifier using conditional patch

    read

    Read the current state of the resource

    search-type

    Search by business identifier to locate an existing resource

Supported Profiles

NDH InsurancePlan Profile

Search Parameters
ConformanceParameterTypeDocumentation
SHOULDidentifiertoken

Business identifier used to select the record for conditional update

 
Core FHIR Resource
Location
Reference Policy
literal, local
Interaction summary
  • SHALL support
    update

    Update an existing resource by its id or by business identifier using conditional update

    read

    Read the current state of the resource

    search-type

    Search by business identifier to locate an existing resource

  • SHOULD support
    create

    Create a new resource with a server assigned id

    patch

    Change individual elements of an existing resource by its id or by business identifier using conditional patch

Supported Profiles

NDH Location Profile

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

Business identifier used to select the record for conditional update

 
Core FHIR Resource
Organization
Reference Policy
literal, local
Interaction summary
  • SHALL support
    update

    Update an existing resource by its id or by business identifier using conditional update

    read

    Read the current state of the resource

    search-type

    Search by business identifier to locate an existing resource

  • SHOULD support
    create

    Create a new resource with a server assigned id

    patch

    Change individual elements of an existing resource by its id or by business identifier using conditional patch

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

Business identifier used to select the record for conditional update

 
Core FHIR Resource
OrganizationAffiliation
Reference Policy
literal, local
Interaction summary
  • SHALL support
    update

    Update an existing resource by its id or by business identifier using conditional update

    read

    Read the current state of the resource

    search-type

    Search by business identifier to locate an existing resource

  • SHOULD support
    create

    Create a new resource with a server assigned id

    patch

    Change individual elements of an existing resource by its id or by business identifier using conditional patch

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

Business identifier used to select the record for conditional update

 
Core FHIR Resource
Practitioner
Reference Policy
literal, local
Interaction summary
  • SHALL support
    update

    Update an existing resource by its id or by business identifier using conditional update

    read

    Read the current state of the resource

    search-type

    Search by business identifier to locate an existing resource

  • SHOULD support
    create

    Create a new resource with a server assigned id

    patch

    Change individual elements of an existing resource by its id or by business identifier using conditional patch

Supported Profiles

NDH Practitioner Profile

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

Business identifier used to select the record for conditional update

 
Core FHIR Resource
PractitionerRole
Reference Policy
literal, local
Interaction summary
  • SHALL support
    update

    Update an existing resource by its id or by business identifier using conditional update

    read

    Read the current state of the resource

    search-type

    Search by business identifier to locate an existing resource

  • SHOULD support
    create

    Create a new resource with a server assigned id

    patch

    Change individual elements of an existing resource by its id or by business identifier using conditional patch

Supported Profiles

NDH PractitionerRole

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

Business identifier used to select the record for conditional update

 
Core FHIR Resource
Group
Reference Policy
literal, local
Interaction summary
  • SHOULD support
    update

    Update an existing resource by its id or by business identifier using conditional update

    create

    Create a new resource with a server assigned id

    patch

    Change individual elements of an existing resource by its id or by business identifier using conditional patch

    read

    Read the current state of the resource

    search-type

    Search by business identifier to locate an existing resource

Supported Profiles

NDH Group

Search Parameters
ConformanceParameterTypeDocumentation
SHOULDidentifiertoken

Business identifier used to select the record for conditional update