Organization

Overview

The Organization resource represents healthcare organizations, payers, and provider groups within the provider directory. Organizations serve as the foundation for provider networks, connecting practitioners, locations, services, and insurance plans.

Key Use Cases:

Find healthcare provider organizations by name or location
Discover payer organizations and their networks
Locate hospital systems and medical groups
Verify organization contact information and addresses

Relationships to Other Resources:

Location - Organizations operate at physical locations
PractitionerRole - Practitioners work for organizations in specific roles
InsurancePlan - Payers offer insurance plans through organizations
OrganizationAffiliation - Organizations have network relationships with other organizations
HealthcareService - Organizations provide healthcare services

Resource Schema

Key fields in the Organization resource:

{
  "resourceType": "Organization",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/npi",
      "value": "1234567890"
    }
  ],
  "active": true,
  "type": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/organization-type",
          "code": "prov|ins|pay|edu|reli|crs|cg|bus|other",
          "display": "Healthcare Provider"
        }
      ]
    }
  ],
  "name": "string",
  "alias": ["string"],
  "telecom": [
    {
      "system": "phone|fax|email|pager|url|sms|other",
      "value": "string",
      "use": "work|home|temp|old|mobile"
    }
  ],
  "address": [
    {
      "use": "work|home|temp|old|billing",
      "line": ["string"],
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string"
    }
  ]
}

Key Fields:

id - Unique identifier for the organization
identifier - External identifiers (NPI, Tax ID, etc.)
name - Official organization name
type - Organization type (provider, payer, etc.)
address - Physical and mailing addresses
telecom - Contact information (phone, email, website)

Operations

Read

Retrieve a specific organization by ID.

Production
Preview

GET /Organization/{id}

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

GET /Organization/{id}

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

Search

Search for organizations using various criteria.

GET Method

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

Production
Preview

GET /Organization?parameter=value

GET /Organization?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production
Preview

POST /Organization/_search

POST /Organization/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
`address`	string	No	Any part of address	`address=Sacramento`
`address-city`	string	No	City name	`address-city=Sacramento`
`address-postalcode`	string	No	ZIP/postal code	`address-postalcode=95814`
`address-state`	string	No	State abbreviation	`address-state=CA`
`identifier`	token	No	External identifier	`identifier=1234567890`
`name`	string	No	Organization name (partial match)	`name=Hospital`
`type`	token	No	Organization type	`type=prov`

Common Search Patterns

Find hospitals in a specific city:

GET /Organization?name=Hospital&address-city=Sacramento&type=prov

Search by organization type:

GET /Organization?type=prov&_count=20

Find organizations by postal code:

GET /Organization?address-postalcode=95814

Search by partial name:

GET /Organization?name=Medical&_count=10

Examples

Request Examples

Production
Preview

Find healthcare providers by name
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Organization/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "name=Hospital&type=prov&_count=10"

Search by geographic area
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Organization/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "address-city=Sacramento&address-state=CA"

Find payer organizations
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Organization/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "type=pay&_count=5"

Find healthcare providers by name
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Organization/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "name=Hospital&type=prov&_count=10"

Search by geographic area
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Organization/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "address-city=Sacramento&address-state=CA"

Find payer organizations
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Organization/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "type=pay&_count=5"

Response Examples

Successful Search Response

Organization Search Bundle
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 3,
  "entry": [
    {
      "resource": {
        "resourceType": "Organization",
        "id": "org-123",
        "identifier": [
          {
            "system": "http://example.org/npi",
            "value": "1234567890"
          }
        ],
        "active": true,
        "type": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/organization-type",
                "code": "prov",
                "display": "Healthcare Provider"
              }
            ]
          }
        ],
        "name": "Sacramento General Hospital",
        "telecom": [
          {
            "system": "phone",
            "value": "(916) 555-0123",
            "use": "work"
          },
          {
            "system": "email",
            "value": "info@sacgeneral.org",
            "use": "work"
          }
        ],
        "address": [
          {
            "use": "work",
            "line": ["1234 Health Way"],
            "city": "Sacramento",
            "state": "CA",
            "postalCode": "95814",
            "country": "US"
          }
        ]
      }
    }
  ]
}

Individual Organization Response

Single Organization Resource
{
  "resourceType": "Organization",
  "id": "org-456",
  "identifier": [
    {
      "system": "http://example.org/npi",
      "value": "9876543210"
    }
  ],
  "active": true,
  "type": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/organization-type",
          "code": "pay",
          "display": "Payer"
        }
      ]
    }
  ],
  "name": "California Health Plan",
  "telecom": [
    {
      "system": "phone",
      "value": "(800) 555-PLAN",
      "use": "work"
    },
    {
      "system": "url",
      "value": "https://www.cahealthplan.com",
      "use": "work"
    }
  ],
  "address": [
    {
      "use": "work",
      "line": ["5678 Insurance Blvd", "Suite 100"],
      "city": "Los Angeles",
      "state": "CA",
      "postalCode": "90210",
      "country": "US"
    }
  ]
}

Empty Result Set

No Organizations Found
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0,
  "entry": []
}

Integration Patterns

Common Workflows

1. Find Provider Organizations in Network

# Step 1: Search for organizations by type and location
GET /Organization?type=prov&address-state=CA

# Step 2: Get locations for specific organization
GET /Location?organization=Organization/org-123

# Step 3: Find practitioners at organization
GET /PractitionerRole?organization=Organization/org-123

2. Discover Payer Networks

# Step 1: Find payer organization
GET /Organization?type=pay&name=HealthPlan

# Step 2: Find insurance plans offered
GET /InsurancePlan?owned-by=Organization/payer-456

# Step 3: Find network affiliations
GET /OrganizationAffiliation?primary-organization=Organization/payer-456

Location - Physical locations where organizations operate
PractitionerRole - Roles practitioners perform for organizations
InsurancePlan - Insurance products offered by payer organizations
OrganizationAffiliation - Network relationships between organizations
HealthcareService - Services provided by organizations

Include Parameters

Use _include to fetch related resources in a single request:

# Get organization with its locations
GET /Organization?name=Hospital&_include=Organization:location

# Get organization with practitioner roles
GET /Organization?type=prov&_include=Organization:practitioner-role

Error Handling

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

Organization-Specific Error Scenarios

404 Not Found: Organization ID doesn't exist or has been deactivated
400 Bad Request: Invalid search parameters or malformed queries
Empty Results: No organizations match the search criteria

Troubleshooting Tips

Empty Results: Try broader search criteria or check if data exists for the region
Invalid Parameters: Verify parameter names match the FHIR specification
Performance Issues: Use _count parameter to limit result sets and improve response times

Overview​

Resource Schema​

Operations​

Read​

Search​

GET Method​

POST Method​

Search Parameters​

Common Search Patterns​

Examples​

Request Examples​

Response Examples​

Successful Search Response​

Individual Organization Response​

Empty Result Set​

Integration Patterns​

Common Workflows​

Related Resources​

Include Parameters​

Error Handling​

Organization-Specific Error Scenarios​

Troubleshooting Tips​

Supported Profiles​