# NDH OrganizationAffiliation Profile - National Directory of Healthcare Providers & Services (NDH) Implementation Guide v2.0.0-current

* [**Table of Contents**](toc.md)
* [**Artifacts Summary**](artifacts.md)
* **NDH OrganizationAffiliation Profile**

## Resource Profile: NDH OrganizationAffiliation Profile 

| | | |
| :--- | :--- | :--- |
| *Official URL*:http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-OrganizationAffiliation | *Version*:2.0.0-current | |
| * Standards status: *[Trial-use](http://hl7.org/fhir/R4/versions.html#std-process) | [Maturity Level](http://hl7.org/fhir/versions.html#maturity): 4 | *Computable Name*:NdhOrganizationAffiliation |

 
The OrganizationAffiliation resource describes relationships between two or more organizations, including the services one organization provides another, the location(s) where they provide services, the availability of those services, electronic endpoints, and other relevant information. 

### Background & Scope

OrganizationAffiliation resource is designed to outline connections between multiple organizations. This includes details on the services provided by one organization to another, the location(s) where services are available, the electronic endpoints used, and other relevant information.

OrganizationAffiliation is useful for defining relationships between organizations that do not have a hierarchical structure. For instance:

* One organization may provide services to another organization
* Two or more organizations may collaborate in a partnership or joint venture
* An organization may be a member of another organization, without being owned by it (for example, a hospital can be a member of the American Hospital Association or a health information exchange network).

OrganizationAffiliation and practitionerRole share a similar structure. However, while practitionerRole references both practitioner and organization, OrganizationAffiliation involves references to a participatingOrg and an organization. The participating organization provides "services" to the primary organization, just as a practitioner provides services to an organization. To illustrate this, here are examples for the three cases mentioned earlier:

The participating organization provides services to the primary organization. In a joint venture, the joint venture itself is the primary organization, while partners within the joint venture are considered participating organizations. This requires two instances of the OrganizationAffiliation resource. In an association, the association is the primary organization, and its members are participating organizations. Additionally, OrganizationAffiliation is used to indicate when an organization provides services for a health insurance provider network.

Each instance has its own time period and can optionally include links to specific related services or locations that are accessible. These referenced locations or services should be associated with the participating organization and may available to the primary organization.

An OrganizationAffiliation role could encompass various healthcare services at multiple locations. When different locations provide distinct services, it is recommended to employ multiple OrganizationAffiliation resources and to separate them by location.

To associate an organization to an active network, it could be achieved by modifying the OrganizationAffiliation.period or for the organization. To change a network, it is necessary to create a new OrganizationAffiliation.

An organization has the capability to be affiliated with multiple networks. However, to ensure clarity and avoid confusion, it is recommended that each OrganizationAffiliation corresponds to only one network, even if the affiliations occur at different times.

**Usages:**

* Refer to this Profile: [NDH Via Intermediary](StructureDefinition-base-ext-via-intermediary.md)
* Examples for this Profile: [OrganizationAffiliation/BurrClinicAffil](OrganizationAffiliation-BurrClinicAffil.md), [OrganizationAffiliation/OrgOneNetwork1Affiliation](OrganizationAffiliation-OrgOneNetwork1Affiliation.md), [OrganizationAffiliation/OrgOneNetwork2Affiliation](OrganizationAffiliation-OrgOneNetwork2Affiliation.md) and [OrganizationAffiliation/PharmChainAffil1](OrganizationAffiliation-PharmChainAffil1.md)
* CapabilityStatements using this Profile: [NDH Server Capability Statement](CapabilityStatement-ndh-server.md)

You can also check for [usages in the FHIR IG Statistics](https://packages2.fhir.org/xig/hl7.fhir.us.ndh|current/StructureDefinition/ndh-OrganizationAffiliation)

### Formal Views of Profile Content

 [Description of Profiles, Differentials, Snapshots and how the different presentations work](http://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#structure-definitions). 

 

Other representations of profile: [CSV](StructureDefinition-ndh-OrganizationAffiliation.csv), [Excel](StructureDefinition-ndh-OrganizationAffiliation.xlsx), [Schematron](StructureDefinition-ndh-OrganizationAffiliation.sch) 

### Notes:

### Search Parameters

#### Search Parameter defined by the NDH IG

| | | |
| :--- | :--- | :--- |
| **SearchParameter Name** | **Type** | **Example** |
| [location](SearchParameter-organizationaffiliation-location.md) | reference | `GET [base]/OrganizationAffiliation?location.address-state=CT` |
| [participating-organization](SearchParameter-organizationaffiliation-participating-organization.md) | reference | `GET [base]/OrganizationAffiliation?participating-organization.address-state=FL` |
| [primary-organization](SearchParameter-organizationaffiliation-primary-organization.md) | reference | `GET [base]/OrganizationAffiliation?primary-organization.address-state=FL` |
| [verification-status](SearchParameter-verification-status.md) | token | `GET [base]/OrganizationAffiliation?verification-status=complete` |

#### Search Parameter defined by FHIR Search Parameter Registry and used by the NDH IG

Since there is no direct individual url for each Search Parameter defined by FHIR Serach Parameter Registry, we have provided the following links for you to access more information about them.

* [Search Parameter Registry](https://hl7.org/fhir/R4/searchparameter-registry.html)
* [OrganizationAffiliation Search Parameter from Registry](https://hl7.org/fhir/R4/organizationaffiliation.html#search)

| | | |
| :--- | :--- | :--- |
| endpoint | reference | `GET [base]/OrganizationAffiliation?endpoint.connection-type=hl7-fhir-rest` |
| identifier | token | `GET [base]/OrganizationAffiliation?identifier=123456` |
| network | reference | `GET [base]/OrganizationAffiliation?network.type=ntwk&network.address-state=FL` |
| role | token | `GET [base]/OrganizationAffiliation?role=group` |
| service | reference | `GET [base]/OrganizationAffiliation?service.address-state=FL` |
| specialty | token | `GET [base]/OrganizationAffiliation?specialty=103T00000X` |

#### _include Search Parameter

| | |
| :--- | :--- |
| OrganizationAffiliation:network | `GET [base]/OrganizationAffiliation?_include=OrganizationAffiliation:network` |
| OrganizationAffiliation:participating-organization | `GET [base]/OrganizationAffiliation?_include=OrganizationAffiliation:participating-organization` |
| OrganizationAffiliation:primary-organization | `GET [base]/OrganizationAffiliation?_include=OrganizationAffiliation:primary-organization` |

#### _revinclude Search Parameter

None

#### Special Search Parameters

The search parameters outlined above are straightforward for basic scenarios but have limitations in handling complex combination queries. To enhance these capabilities, employing the special search parameters [_filter](https://hl7.org/fhir/R5/search_filter.html#3.2.3) is recommended.

#### Why is the Qualification Extension Needed in Organization Affiliation?

The qualification extension in the OrganizationAffiliation Resource is significant as it offers a valid use case in real-world practice. For instance, an oncology group seeking privileges to practice in a hospital setting typically requires various approvals and certifications. This includes each physician in the group being licensed to practice medicine in the state where the hospital is located. Additionally, each physician must apply for and be granted the privilege to practice at the specific hospital. Furthermore, the oncology practice itself may also seek accreditation from organizations such as the Commission on Cancer (CoC) or the Quality Oncology Practice Initiative (QOPI), which can bolster its reputation and demonstrate a commitment to quality care. The qualifications of the oncology practice reflect its specific credential to the hospital where they practice. Although these qualifications can be documented in the oncology practice organization resource, an organization may have several qualifications, of which only certain ones are relevant to a specific practice setting. Therefore, it is necessary for both the OrganizationAffiliation Resource and the Organization Resource to include a qualification extension that serves different functions across various contexts.

#### Search

Search OrganizationAffiliation resource based on the role of the participatingOrganization: Get [base]/OrganizationAffiliation?code=HieInitiator

 Search OrganizationAffiliation resources which have participatingOrganization present: Get [base]/OrganizationAffiliation?_include=OrganizationAffiliation:participatingOrganization

 Search Organization resource which associate with OrganizationAffiliation: Get [base]/Organization?_revinclude=OrganizationAffiliation:participatingOrganization



## Resource Content

```json
{
  "resourceType" : "StructureDefinition",
  "id" : "ndh-OrganizationAffiliation",
  "extension" : [{
    "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-wg",
    "valueCode" : "pa"
  },
  {
    "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm",
    "valueInteger" : 4,
    "_valueInteger" : {
      "extension" : [{
        "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom",
        "valueCanonical" : "http://hl7.org/fhir/us/ndh/ImplementationGuide/hl7.fhir.us.ndh"
      }]
    }
  },
  {
    "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status",
    "valueCode" : "trial-use",
    "_valueCode" : {
      "extension" : [{
        "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom",
        "valueCanonical" : "http://hl7.org/fhir/us/ndh/ImplementationGuide/hl7.fhir.us.ndh"
      }]
    }
  }],
  "url" : "http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-OrganizationAffiliation",
  "version" : "2.0.0-current",
  "name" : "NdhOrganizationAffiliation",
  "title" : "NDH OrganizationAffiliation Profile",
  "status" : "active",
  "date" : "2026-03-23T21:58:05+00:00",
  "publisher" : "HL7 International / Patient Administration",
  "contact" : [{
    "name" : "HL7 International / Patient Administration",
    "telecom" : [{
      "system" : "url",
      "value" : "http://www.hl7.org/Special/committees/pafm"
    },
    {
      "system" : "email",
      "value" : "pafm@lists.hl7.org"
    }]
  }],
  "description" : "The OrganizationAffiliation resource describes relationships between two or more organizations, including the services one organization provides another, \nthe location(s) where they provide services, the availability of those services, electronic endpoints, and other relevant information.",
  "jurisdiction" : [{
    "coding" : [{
      "system" : "urn:iso:std:iso:3166",
      "code" : "US",
      "display" : "United States of America"
    }]
  }],
  "fhirVersion" : "4.0.1",
  "mapping" : [{
    "identity" : "ndh-to-plannet-organizationaffiliation",
    "uri" : "http://hl7.org/fhir/us/davinci-pdex-plan-net",
    "name" : "NDH to Plan-Net OrganizationAffiliation Mapping",
    "comment" : "Maps NDH OrganizationAffiliation profile to the Plan-Net OrganizationAffiliation profile, noting elements not present in Plan-Net."
  },
  {
    "identity" : "rim",
    "uri" : "http://hl7.org/v3",
    "name" : "RIM Mapping"
  },
  {
    "identity" : "w5",
    "uri" : "http://hl7.org/fhir/fivews",
    "name" : "FiveWs Pattern Mapping"
  }],
  "kind" : "resource",
  "abstract" : false,
  "type" : "OrganizationAffiliation",
  "baseDefinition" : "http://hl7.org/fhir/StructureDefinition/OrganizationAffiliation",
  "derivation" : "constraint",
  "differential" : {
    "element" : [{
      "id" : "OrganizationAffiliation",
      "path" : "OrganizationAffiliation",
      "constraint" : [{
        "key" : "organization-or-participatingOrganization",
        "severity" : "error",
        "human" : "NdhOrganizationAffiliation.organization or  NdhOrganizationAffiliation.participatingOrganization",
        "expression" : "organization.exists() or participatingOrganization.exists()",
        "source" : "http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-OrganizationAffiliation"
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "OrganizationAffiliation",
        "comment" : "Top-level mapping from NDH to Plan-Net"
      }]
    },
    {
      "id" : "OrganizationAffiliation.meta.lastUpdated",
      "path" : "OrganizationAffiliation.meta.lastUpdated",
      "min" : 1,
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "OrganizationAffiliation.meta.lastUpdated",
        "comment" : ", is required in NDH"
      }]
    },
    {
      "id" : "OrganizationAffiliation.extension",
      "path" : "OrganizationAffiliation.extension",
      "slicing" : {
        "discriminator" : [{
          "type" : "value",
          "path" : "url"
        }],
        "ordered" : false,
        "rules" : "open"
      }
    },
    {
      "id" : "OrganizationAffiliation.extension:qualification",
      "path" : "OrganizationAffiliation.extension",
      "sliceName" : "qualification",
      "short" : "Qualification",
      "min" : 0,
      "max" : "*",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-qualification"]
      }]
    },
    {
      "id" : "OrganizationAffiliation.extension:verification-status",
      "path" : "OrganizationAffiliation.extension",
      "sliceName" : "verification-status",
      "min" : 0,
      "max" : "1",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-verification-status"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "Not in Plan-Net",
        "comment" : ", NDH-specific"
      }]
    },
    {
      "id" : "OrganizationAffiliation.extension:logo",
      "path" : "OrganizationAffiliation.extension",
      "sliceName" : "logo",
      "min" : 0,
      "max" : "1",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-logo"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "Not in Plan-Net",
        "comment" : ", NDH Network-specific"
      }]
    },
    {
      "id" : "OrganizationAffiliation.identifier",
      "path" : "OrganizationAffiliation.identifier",
      "mustSupport" : true,
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "OrganizationAffiliation.identifier"
      }]
    },
    {
      "id" : "OrganizationAffiliation.identifier.extension:identifier-status",
      "path" : "OrganizationAffiliation.identifier.extension",
      "sliceName" : "identifier-status",
      "min" : 0,
      "max" : "1",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-identifier-status"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "Not in Plan-Net",
        "comment" : ", NDH-specific"
      }]
    },
    {
      "id" : "OrganizationAffiliation.identifier.assigner",
      "path" : "OrganizationAffiliation.identifier.assigner",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Organization"]
      }]
    },
    {
      "id" : "OrganizationAffiliation.active",
      "path" : "OrganizationAffiliation.active",
      "min" : 1,
      "patternBoolean" : true
    },
    {
      "id" : "OrganizationAffiliation.period",
      "path" : "OrganizationAffiliation.period",
      "mustSupport" : true
    },
    {
      "id" : "OrganizationAffiliation.organization",
      "path" : "OrganizationAffiliation.organization",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Organization"]
      }],
      "mustSupport" : true,
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "OrganizationAffiliation.organization",
        "comment" : ", using NDH Organization Profile"
      }]
    },
    {
      "id" : "OrganizationAffiliation.participatingOrganization",
      "path" : "OrganizationAffiliation.participatingOrganization",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Organization"]
      }],
      "mustSupport" : true,
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "OrganizationAffiliation.participatingOrganization",
        "comment" : ", using NDH Organization Profile"
      }]
    },
    {
      "id" : "OrganizationAffiliation.network",
      "path" : "OrganizationAffiliation.network",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Network"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "OrganizationAffiliation.network",
        "comment" : ", using NDH Network Profile"
      }]
    },
    {
      "id" : "OrganizationAffiliation.code",
      "path" : "OrganizationAffiliation.code",
      "binding" : {
        "strength" : "extensible",
        "valueSet" : "http://hl7.org/fhir/us/ndh/ValueSet/OrganizationAffiliationRoleVS"
      }
    },
    {
      "id" : "OrganizationAffiliation.specialty",
      "path" : "OrganizationAffiliation.specialty",
      "binding" : {
        "extension" : [{
          "extension" : [{
            "url" : "key",
            "valueId" : "NDH-OrganizationAffiliation-specialty"
          },
          {
            "url" : "purpose",
            "valueCode" : "extensible"
          },
          {
            "url" : "valueSet",
            "valueCanonical" : "http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.114222.4.11.1066|20240606"
          },
          {
            "url" : "documentation",
            "valueMarkdown" : "The specialty(ies) of the participating organization in this affiliation."
          },
          {
            "url" : "shortDoco",
            "valueString" : "The specialty(ies) at the organization in this affiliation."
          }],
          "url" : "http://hl7.org/fhir/tools/StructureDefinition/additional-binding"
        }],
        "strength" : "preferred",
        "description" : "Specific specialty associated with the participating organization.",
        "valueSet" : "http://hl7.org/fhir/ValueSet/c80-practice-codes"
      }
    },
    {
      "id" : "OrganizationAffiliation.location",
      "path" : "OrganizationAffiliation.location",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Location"]
      }],
      "mustSupport" : true,
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "OrganizationAffiliation.location",
        "comment" : ", using NDH Location Profile"
      }]
    },
    {
      "id" : "OrganizationAffiliation.healthcareService",
      "path" : "OrganizationAffiliation.healthcareService",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-HealthcareService"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "OrganizationAffiliation.healthcareService",
        "comment" : ", using NDH HealthcareService Profile"
      }]
    },
    {
      "id" : "OrganizationAffiliation.telecom",
      "path" : "OrganizationAffiliation.telecom",
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "OrganizationAffiliation.telecom"
      }]
    },
    {
      "id" : "OrganizationAffiliation.telecom.extension:contactpoint-availabletime",
      "path" : "OrganizationAffiliation.telecom.extension",
      "sliceName" : "contactpoint-availabletime",
      "min" : 0,
      "max" : "*",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-contactpoint-availabletime"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "Not in Plan-Net",
        "comment" : ", NDH-specific"
      }]
    },
    {
      "id" : "OrganizationAffiliation.telecom.extension:via-intermediary",
      "path" : "OrganizationAffiliation.telecom.extension",
      "sliceName" : "via-intermediary",
      "short" : "Via Intermediary",
      "min" : 0,
      "max" : "1",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-via-intermediary"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "Not in Plan-Net",
        "comment" : ", NDH-specific"
      }]
    },
    {
      "id" : "OrganizationAffiliation.endpoint",
      "path" : "OrganizationAffiliation.endpoint",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Endpoint"]
      }],
      "mustSupport" : true,
      "mapping" : [{
        "identity" : "ndh-to-plannet-organizationaffiliation",
        "map" : "OrganizationAffiliation.endpoint",
        "comment" : ", using NDH Endpoint Profile"
      }]
    }]
  }
}

```
