OrganizationAffiliation

Overview

The OrganizationAffiliation resource defines relationships and affiliations between organizations that are not hierarchical parent-child relationships. It represents network memberships, partnerships, and other collaborative relationships within provider directories.

Key Use Cases:

Discover provider network memberships
Find organizational partnerships and affiliations
Verify network relationships between payers and providers
Locate organizations within specific networks

Relationships to Other Resources:

Organization - Primary and participating organizations in the affiliation
Location - Locations where the affiliation applies
HealthcareService - Services provided through the affiliation
Endpoint - Technical endpoints for affiliation services

Resource Schema

Key fields in the OrganizationAffiliation resource:

{
  "resourceType": "OrganizationAffiliation",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/affiliation-id",
      "value": "AFF-123"
    }
  ],
  "active": true,
  "period": {
    "start": "2024-01-01",
    "end": "2024-12-31"
  },
  "organization": {
    "reference": "Organization/network-123",
    "display": "Western Provider Network"
  },
  "participatingOrganization": {
    "reference": "Organization/provider-456",
    "display": "Sacramento Medical Group"
  },
  "network": [
    {
      "reference": "Organization/insurance-network",
      "display": "Premium Health Network"
    }
  ],
  "code": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/organization-role",
          "code": "provider",
          "display": "Provider"
        }
      ]
    }
  ],
  "specialty": [
    {
      "coding": [
        {
          "system": "http://nucc.org/provider-taxonomy",
          "code": "207R00000X",
          "display": "Internal Medicine"
        }
      ]
    }
  ],
  "location": [
    {
      "reference": "Location/clinic-789",
      "display": "Main Clinic"
    }
  ],
  "healthcareService": [
    {
      "reference": "HealthcareService/primary-care"
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "(916) 555-0180",
      "use": "work"
    }
  ],
  "endpoint": [
    {
      "reference": "Endpoint/provider-portal"
    }
  ]
}

Key Fields:

organization - Primary organization (often the network)
participatingOrganization - Organization participating in the network
network - Insurance or provider network
code - Type of role in the affiliation
specialty - Specialties covered by the affiliation
location - Where the affiliation applies

Operations

Read

Retrieve a specific organization affiliation by ID.

Production
Preview

GET /OrganizationAffiliation/{id}

Example Request
curl -X GET https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/OrganizationAffiliation/aff-123 \
    -H "Accept: application/fhir+json"

GET /OrganizationAffiliation/{id}

Example Request
curl -X GET https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/OrganizationAffiliation/aff-123 \
    -H "Accept: application/fhir+json"

Search

Search for organization affiliations using various criteria.

GET Method

Use GET for simple searches with parameters in the query string.

Production
Preview

GET /OrganizationAffiliation?parameter=value

GET /OrganizationAffiliation?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production
Preview

POST /OrganizationAffiliation/_search

POST /OrganizationAffiliation/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
`date`	date	No	Affiliation period	`date=2024-01-01`
`location`	reference	No	Location where affiliation applies	`location=Location/clinic-789`
`network`	reference	No	Network organization	`network=Organization/insurance-network`
`participating-organization`	reference	No	Participating organization	`participating-organization=Organization/provider-456`
`primary-organization`	reference	No	Primary organization in affiliation	`primary-organization=Organization/network-123`
`role`	token	No	Role type in affiliation	`role=provider`
`service`	reference	No	Healthcare service in affiliation	`service=HealthcareService/primary-care`
`specialty`	token	No	Specialty covered by affiliation	`specialty=207R00000X`

Common Search Patterns

Find network memberships:

GET /OrganizationAffiliation?network=Organization/insurance-network&_count=10

Search by participating organization:

GET /OrganizationAffiliation?participating-organization=Organization/provider-456

Find affiliations by specialty:

GET /OrganizationAffiliation?specialty=207R00000X

Search by location:

GET /OrganizationAffiliation?location=Location/clinic-789

Examples

Request Examples

Production
Preview

Find provider network memberships
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/OrganizationAffiliation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "network=Organization/insurance-network&role=provider"

Search affiliations by organization
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/OrganizationAffiliation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "participating-organization=Organization/provider-456&_include=OrganizationAffiliation:primary-organization"

Find specialty-specific affiliations
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/OrganizationAffiliation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "specialty=207RC0000X&location.address-state=CA"

Find provider network memberships
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/OrganizationAffiliation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "network=Organization/insurance-network&role=provider"

Search affiliations by organization
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/OrganizationAffiliation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "participating-organization=Organization/provider-456&_include=OrganizationAffiliation:primary-organization"

Find specialty-specific affiliations
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/OrganizationAffiliation/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "specialty=207RC0000X&location.address-state=CA"

Response Examples

Successful Search Response

OrganizationAffiliation Search Bundle
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "OrganizationAffiliation",
        "id": "aff-123",
        "active": true,
        "organization": {
          "reference": "Organization/network-456",
          "display": "California Provider Network"
        },
        "participatingOrganization": {
          "reference": "Organization/provider-789",
          "display": "Bay Area Medical Group"
        },
        "network": [
          {
            "reference": "Organization/insurance-network",
            "display": "Premium Health Network"
          }
        ],
        "code": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/organization-role",
                "code": "provider",
                "display": "Provider"
              }
            ]
          }
        ],
        "specialty": [
          {
            "coding": [
              {
                "system": "http://nucc.org/provider-taxonomy",
                "code": "207RC0000X",
                "display": "Cardiovascular Disease"
              }
            ]
          }
        ],
        "location": [
          {
            "reference": "Location/clinic-101",
            "display": "Cardiology Clinic"
          }
        ]
      }
    }
  ]
}

Integration Patterns

Common Workflows

1. Discover Provider Networks

# Step 1: Find provider organization
GET /Organization?name=Medical Group&type=prov

# Step 2: Get all network affiliations
GET /OrganizationAffiliation?participating-organization=Organization/provider-456

# Step 3: Get network details
GET /Organization/network-789

2. Find Network Providers by Specialty

# Step 1: Find affiliations by network and specialty
GET /OrganizationAffiliation?network=Organization/insurance-network&specialty=207RC0000X

# Step 2: Get participating organization details
GET /Organization/provider-789

# Step 3: Find practitioners at organization
GET /PractitionerRole?organization=Organization/provider-789

Organization - Primary and participating organizations
Location - Where affiliations apply
HealthcareService - Services provided through affiliations
InsurancePlan - Insurance plans associated with networks

Include Parameters

Use _include to fetch related resources:

# Get affiliations with organization details
GET /OrganizationAffiliation?network=Organization/network-123&_include=OrganizationAffiliation:participating-organization

# Get affiliations with location details
GET /OrganizationAffiliation?specialty=cardiology&_include=OrganizationAffiliation:location

Error Handling

The OrganizationAffiliation resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the Common Errors page.