National Healthcare Directory Attestation and Verification
1.0.0-ballot - ballot

National Healthcare Directory Attestation and Verification, published by HL7 Patient Administration Working Group. This is not an authorized publication; it is the continuous build for version 1.0.0-ballot). This version is based on the current content of https://github.com/HL7/fhir-directory-attestation/ and changes regularly. See the Directory of published versions

## CapabilityStatement: NatlDir CapabilityStatement

Official URL: http://hl7.org/fhir/us/directory-attestation/CapabilityStatement/NatlDir | Version: 1.0.0-ballot
Active as of 2020-11-19 | Computable Name: DavinciPdexNatlDirCapabilityStatement

This Section describes the expected capabilities of the NatlDir Server actor which is responsible for providing responses to the queries submitted by the NatlDir Requestors. The complete list of FHIR profiles, RESTful operations, and search parameters supported by NatlDir Servers are defined. Systems implementing this capability statement should meet the CMS FInal Rule requirement for provider directory access. NatlDir Clients can use the required capabilities to access necessary data based on their local use cases and other contextual requirements.

Raw OpenAPI-Swagger Definition file | Download

## NatlDir CapabilityStatement

- Implementation Guide Version: 1.0.0
- FHIR Version: 4.0.1
- Supported formats: xml, json
- Published: 2020-11-19
- Published by: HL7 Financial Management Working Group (FM WG)

This Section describes the expected capabilities of the NatlDir Server actor which is responsible for providing responses to the queries submitted by the NatlDir Requestors. The complete list of FHIR profiles, RESTful operations, and search parameters supported by NatlDir Servers are defined. Systems implementing this capability statement should meet the CMS FInal Rule requirement for provider directory access. NatlDir Clients can use the required capabilities to access necessary data based on their local use cases and other contextual requirements.

### FHIR RESTful Capabilities

The NatlDir Server SHALL:

1. Support all profiles defined in this Implementation Guide..
2. Implement the RESTful behavior according to the FHIR specification.
3. Return the following response classes:
   - (Status 400): invalid parameter
   - (Status 401/4xx): unauthorized request
   - (Status 403): insufficient scope
   - (Status 404): unknown resource
   - (Status 410): deleted resource.
4. Support json source formats for all NatlDir interactions.
5. Identify the NatlDir profiles supported as part of the FHIR `meta.profile` attribute for each instance.
6. Support the searchParameters on each profile individually and in combination. 1.Support forward and reverse chaining on all search parameters that specify the 'chain' property

The NatlDir Server SHOULD:

1. Support xml source formats for all NatlDir interactions.

Security:

1. See the General Security Considerations section for requirements and recommendations.
2. A server SHALL reject any unauthorized requests by returning an `HTTP 401` unauthorized response code.

### RESTful Capabilities by Resource/Profile:

Summary of Search Criteria

Resource Type | Supported Profiles | Supported Searches | Supported `_includes` | Supported `_revincludes` | Supported Operations
--- | --- | --- | --- | --- | ---
Endpoint | NatlDir Endpoint | organization, _id, _lastUpdated | Endpoint:organization |  |
HealthcareService | NatlDir HealthcareService | location, coverage-area, organization, endpoint, name, service-category, service-type, specialty, _id, _lastUpdated | HealthcareService:location, HealthcareService:coverage-area, HealthcareService:organization, HealthcareService:endpoint | PractitionerRole:service, OrganizationAffiliation:service |
InsurancePlan | NatlDir InsurancePlan | administered-by, owned-by, coverage-area, name, plan-type, identifier, _id, _lastUpdated, type | InsurancePlan:administered-by, InsurancePlan:owned-by, InsurancePlan:coverage-area |  |
Location | NatlDir Location | partof, organization, endpoint, address-city, address-state, address-postalcode, address, type, _id, _lastUpdated | Location:endpoint, Location:organization, Location:partof | HealthcareService:location, InsurancePlan:coverage-area, OrganizationAffiliation:location, PractitionerRole:location |
Organization | NatlDir Network, NatlDir Organization | partof, endpoint, address, name, _id, _lastUpdated, type, coverage-area | Organization:partof, Organization:endpoint, Organization:coverage-area | Endpoint:organization, HealthcareService:organization, InsurancePlan:administered-by, InsurancePlan:owned-by, OrganizationAffiliation:primary-organization, PractitionerRole:organization, PractitionerRole:network, OrganizationAffiliation:participating-organization |
OrganizationAffiliation | NatlDir OrganizationAffiliation | primary-organization, participating-organization, location, service, network, endpoint, role, specialty, _id, _lastUpdated | OrganizationAffiliation:primary-organization, OrganizationAffiliation:participating-organization, OrganizationAffiliation:location, OrganizationAffiliation:service, OrganizationAffiliation:endpoint, OrganizationAffiliation:network |  |
Practitioner | NatlDir Practitioner | name, _id, _lastUpdated, family, given |  | PractitionerRole:practitioner |
PractitionerRole | NatlDir PractitionerRole | practitioner, organization, location, service, network, endpoint, role, specialty, _id, _lastUpdated | PractitionerRole:practitioner, PractitionerRole:organization, PractitionerRole:location, PractitionerRole:service, PractitionerRole:network, PractitionerRole:endpoint |  |

#### Endpoint

Conformance Expectation: SHALL

Supported Profiles: NatlDir Endpoint

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `search-type`, `read`.
- SHOULD support `vread`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a Endpoint resource using:
  `GET [base]/Endpoint/[id]`
- A Server SHOULD be capable of returning a Endpoint resource using:
  `GET [base]/Endpoint/[id]/_history/vid`
- A Server SHALL be capable of supporting the following _includes:
  Endpoint:organization - `GET [base]/Endpoint?[parameter=value]&_include=Endpoint:organization`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHALL | organization | reference | `GET [base]/Endpoint?organization=[organization]`
SHALL | _id | token | `GET [base]/Endpoint?_id=[id]`
SHALL | _lastUpdated | date | `GET [base]/Endpoint?_lastUpdated=[_lastUpdated]`

#### HealthcareService

Conformance Expectation: SHALL

Supported Profiles: NatlDir HealthcareService

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `search-type`, `read`.
- SHOULD support `vread`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a HealthcareService resource using:
  `GET [base]/HealthcareService/[id]`
- A Server SHOULD be capable of returning a HealthcareService resource using:
  `GET [base]/HealthcareService/[id]/_history/vid`
- A Server SHALL be capable of supporting the following _includes:
  HealthcareService:location - `GET [base]/HealthcareService?[parameter=value]&_include=HealthcareService:location`
  HealthcareService:coverage-area - `GET [base]/HealthcareService?[parameter=value]&_include=HealthcareService:coverage-area`
  HealthcareService:organization - `GET [base]/HealthcareService?[parameter=value]&_include=HealthcareService:organization`
  HealthcareService:endpoint - `GET [base]/HealthcareService?[parameter=value]&_include=HealthcareService:endpoint`
- A Server SHALL be capable of supporting the following _revincludes:
  PractitionerRole:service - `GET [base]/HealthcareService?[parameter=value]&_revinclude=PractitionerRole:service`
  OrganizationAffiliation:service - `GET [base]/HealthcareService?[parameter=value]&_revinclude=OrganizationAffiliation:service`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHALL | location | reference | `GET [base]/HealthcareService?location=[location]`
SHALL | coverage-area | reference | `GET [base]/HealthcareService?coverage-area=[coverage-area]`
SHALL | organization | reference | `GET [base]/HealthcareService?organization=[organization]`
SHALL | endpoint | reference | `GET [base]/HealthcareService?endpoint=[endpoint]`
SHALL | name | string | `GET [base]/HealthcareService?name=[name]`
SHALL | service-category | token | `GET [base]/HealthcareService?service-category=[system]|[code]`
SHALL | service-type | token | `GET [base]/HealthcareService?service-type=[system]|[code]`
SHALL | specialty | token | `GET [base]/HealthcareService?specialty=[system]|[code]`
SHALL | _id | token | `GET [base]/HealthcareService?_id=[id]`
SHALL | _lastUpdated | date | `GET [base]/HealthcareService?_lastUpdated=[_lastUpdated]`

#### InsurancePlan

Conformance Expectation: SHALL

Supported Profiles: NatlDir InsurancePlan

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `search-type`, `read`.
- SHOULD support `vread`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a InsurancePlan resource using:
  `GET [base]/InsurancePlan/[id]`
- A Server SHOULD be capable of returning a InsurancePlan resource using:
  `GET [base]/InsurancePlan/[id]/_history/vid`
- A Server SHALL be capable of supporting the following _includes:
  InsurancePlan:administered-by - `GET [base]/InsurancePlan?[parameter=value]&_include=InsurancePlan:administered-by`
  InsurancePlan:owned-by - `GET [base]/InsurancePlan?[parameter=value]&_include=InsurancePlan:owned-by`
  InsurancePlan:coverage-area - `GET [base]/InsurancePlan?[parameter=value]&_include=InsurancePlan:coverage-area`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHALL | administered-by | reference | `GET [base]/InsurancePlan?administered-by=[administered-by]`
SHALL | owned-by | reference | `GET [base]/InsurancePlan?owned-by=[owned-by]`
SHALL | coverage-area | reference | `GET [base]/InsurancePlan?coverage-area=[coverage-area]`
SHALL | name | string | `GET [base]/InsurancePlan?name=[name]`
SHALL | plan-type | token | `GET [base]/InsurancePlan?plan-type=[system]|[code]`
SHALL | identifier | token | `GET [base]/InsurancePlan?identifier=[system]|[code]`
SHALL | _id | token | `GET [base]/InsurancePlan?_id=[id]`
SHALL | _lastUpdated | date | `GET [base]/InsurancePlan?_lastUpdated=[_lastUpdated]`
SHALL | type | token | `GET [base]/InsurancePlan?type=[system]|[code]`

#### Location

Conformance Expectation: SHALL

Supported Profiles: NatlDir Location

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `search-type`, `read`.
- SHOULD support `vread`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a Location resource using:
  `GET [base]/Location/[id]`
- A Server SHOULD be capable of returning a Location resource using:
  `GET [base]/Location/[id]/_history/vid`
- A Server SHALL be capable of supporting the following _includes:
  Location:endpoint - `GET [base]/Location?[parameter=value]&_include=Location:endpoint`
  Location:organization - `GET [base]/Location?[parameter=value]&_include=Location:organization`
  Location:partof - `GET [base]/Location?[parameter=value]&_include=Location:partof`
- A Server SHALL be capable of supporting the following _revincludes:
  HealthcareService:location - `GET [base]/Location?[parameter=value]&_revinclude=HealthcareService:location`
  InsurancePlan:coverage-area - `GET [base]/Location?[parameter=value]&_revinclude=InsurancePlan:coverage-area`
  OrganizationAffiliation:location - `GET [base]/Location?[parameter=value]&_revinclude=OrganizationAffiliation:location`
  PractitionerRole:location - `GET [base]/Location?[parameter=value]&_revinclude=PractitionerRole:location`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHALL | partof | reference | `GET [base]/Location?partof=[partof]`
SHALL | organization | reference | `GET [base]/Location?organization=[organization]`
SHALL | endpoint | reference | `GET [base]/Location?endpoint=[endpoint]`
SHALL | address-city | string | `GET [base]/Location?address-city=[address-city]`
SHALL | address-state | string | `GET [base]/Location?address-state=[address-state]`
SHALL | address-postalcode | string | `GET [base]/Location?address-postalcode=[address-postalcode]`
SHALL | address | string | `GET [base]/Location?address=[address]`
SHALL | type | token | `GET [base]/Location?type=[system]|[code]`
SHALL | _id | token | `GET [base]/Location?_id=[id]`
SHALL | _lastUpdated | date | `GET [base]/Location?_lastUpdated=[_lastUpdated]`

#### Organization

Conformance Expectation: SHALL

Supported Profiles: NatlDir Network, NatlDir Organization

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `search-type`, `read`.
- SHOULD support `vread`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a Organization resource using:
  `GET [base]/Organization/[id]`
- A Server SHOULD be capable of returning a Organization resource using:
  `GET [base]/Organization/[id]/_history/vid`
- A Server SHALL be capable of supporting the following _includes:
  Organization:partof - `GET [base]/Organization?[parameter=value]&_include=Organization:partof`
  Organization:endpoint - `GET [base]/Organization?[parameter=value]&_include=Organization:endpoint`
  Organization:coverage-area - `GET [base]/Organization?[parameter=value]&_include=Organization:coverage-area`
- A Server SHALL be capable of supporting the following _revincludes:
  Endpoint:organization - `GET [base]/Organization?[parameter=value]&_revinclude=Endpoint:organization`
  HealthcareService:organization - `GET [base]/Organization?[parameter=value]&_revinclude=HealthcareService:organization`
  InsurancePlan:administered-by - `GET [base]/Organization?[parameter=value]&_revinclude=InsurancePlan:administered-by`
  InsurancePlan:owned-by - `GET [base]/Organization?[parameter=value]&_revinclude=InsurancePlan:owned-by`
  OrganizationAffiliation:primary-organization - `GET [base]/Organization?[parameter=value]&_revinclude=OrganizationAffiliation:primary-organization`
  PractitionerRole:organization - `GET [base]/Organization?[parameter=value]&_revinclude=PractitionerRole:organization`
  PractitionerRole:network - `GET [base]/Organization?[parameter=value]&_revinclude=PractitionerRole:network`
  OrganizationAffiliation:participating-organization - `GET [base]/Organization?[parameter=value]&_revinclude=OrganizationAffiliation:participating-organization`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHALL | partof | reference | `GET [base]/Organization?partof=[partof]`
SHALL | endpoint | reference | `GET [base]/Organization?endpoint=[endpoint]`
SHALL | address | string | `GET [base]/Organization?address=[address]`
SHALL | name | string | `GET [base]/Organization?name=[name]`
SHALL | _id | token | `GET [base]/Organization?_id=[id]`
SHALL | _lastUpdated | date | `GET [base]/Organization?_lastUpdated=[_lastUpdated]`
SHALL | type | token | `GET [base]/Organization?type=[system]|[code]`
SHALL | coverage-area | reference | `GET [base]/Organization?coverage-area=[coverage-area]`

#### OrganizationAffiliation

Conformance Expectation: SHALL

Supported Profiles: NatlDir OrganizationAffiliation

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `search-type`, `read`.
- SHOULD support `vread`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a OrganizationAffiliation resource using:
  `GET [base]/OrganizationAffiliation/[id]`
- A Server SHOULD be capable of returning a OrganizationAffiliation resource using:
  `GET [base]/OrganizationAffiliation/[id]/_history/vid`
- A Server SHALL be capable of supporting the following _includes:
  OrganizationAffiliation:primary-organization - `GET [base]/OrganizationAffiliation?[parameter=value]&_include=OrganizationAffiliation:primary-organization`
  OrganizationAffiliation:participating-organization - `GET [base]/OrganizationAffiliation?[parameter=value]&_include=OrganizationAffiliation:participating-organization`
  OrganizationAffiliation:location - `GET [base]/OrganizationAffiliation?[parameter=value]&_include=OrganizationAffiliation:location`
  OrganizationAffiliation:service - `GET [base]/OrganizationAffiliation?[parameter=value]&_include=OrganizationAffiliation:service`
  OrganizationAffiliation:endpoint - `GET [base]/OrganizationAffiliation?[parameter=value]&_include=OrganizationAffiliation:endpoint`
  OrganizationAffiliation:network - `GET [base]/OrganizationAffiliation?[parameter=value]&_include=OrganizationAffiliation:network`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHALL | primary-organization | reference | `GET [base]/OrganizationAffiliation?primary-organization=[primary-organization]`
SHALL | participating-organization | reference | `GET [base]/OrganizationAffiliation?participating-organization=[participating-organization]`
SHALL | location | reference | `GET [base]/OrganizationAffiliation?location=[location]`
SHALL | service | reference | `GET [base]/OrganizationAffiliation?service=[service]`
SHALL | network | reference | `GET [base]/OrganizationAffiliation?network=[network]`
SHALL | endpoint | reference | `GET [base]/OrganizationAffiliation?endpoint=[endpoint]`
SHALL | role | token | `GET [base]/OrganizationAffiliation?role=[system]|[code]`
SHALL | specialty | token | `GET [base]/OrganizationAffiliation?specialty=[system]|[code]`
SHALL | _id | token | `GET [base]/OrganizationAffiliation?_id=[id]`
SHALL | _lastUpdated | date | `GET [base]/OrganizationAffiliation?_lastUpdated=[_lastUpdated]`

#### Practitioner

Conformance Expectation: SHALL

Supported Profiles: NatlDir Practitioner

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `search-type`, `read`.
- SHOULD support `vread`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a Practitioner resource using:
  `GET [base]/Practitioner/[id]`
- A Server SHOULD be capable of returning a Practitioner resource using:
  `GET [base]/Practitioner/[id]/_history/vid`
- A Server SHALL be capable of supporting the following _revincludes:
  PractitionerRole:practitioner - `GET [base]/Practitioner?[parameter=value]&_revinclude=PractitionerRole:practitioner`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHALL | name | string | `GET [base]/Practitioner?name=[name]`
SHALL | _id | token | `GET [base]/Practitioner?_id=[id]`
SHALL | _lastUpdated | date | `GET [base]/Practitioner?_lastUpdated=[_lastUpdated]`
SHALL | family | string | `GET [base]/Practitioner?family=[family]`
SHALL | given | string | `GET [base]/Practitioner?given=[given]`

#### PractitionerRole

Conformance Expectation: SHALL

Supported Profiles: NatlDir PractitionerRole

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `search-type`, `read`.
- SHOULD support `vread`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a PractitionerRole resource using:
  `GET [base]/PractitionerRole/[id]`
- A Server SHOULD be capable of returning a PractitionerRole resource using:
  `GET [base]/PractitionerRole/[id]/_history/vid`
- A Server SHALL be capable of supporting the following _includes:
  PractitionerRole:practitioner - `GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:practitioner`
  PractitionerRole:organization - `GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:organization`
  PractitionerRole:location - `GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:location`
  PractitionerRole:service - `GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:service`
  PractitionerRole:network - `GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:network`
  PractitionerRole:endpoint - `GET [base]/PractitionerRole?[parameter=value]&_include=PractitionerRole:endpoint`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHALL | practitioner | reference | `GET [base]/PractitionerRole?practitioner=[practitioner]`
SHALL | organization | reference | `GET [base]/PractitionerRole?organization=[organization]`
SHALL | location | reference | `GET [base]/PractitionerRole?location=[location]`
SHALL | service | reference | `GET [base]/PractitionerRole?service=[service]`
SHALL | network | reference | `GET [base]/PractitionerRole?network=[network]`
SHALL | endpoint | reference | `GET [base]/PractitionerRole?endpoint=[endpoint]`
SHALL | role | token | `GET [base]/PractitionerRole?role=[system]|[code]`
SHALL | specialty | token | `GET [base]/PractitionerRole?specialty=[system]|[code]`
SHALL | _id | token | `GET [base]/PractitionerRole?_id=[id]`
SHALL | _lastUpdated | date | `GET [base]/PractitionerRole?_lastUpdated=[_lastUpdated]`