Organization

Overview

The Organization resource represents healthcare organizations, payers, and provider groups within the Payer System Access API. Organizations serve as the foundation for healthcare delivery, connecting practitioners, locations, and services in patient care.

Key Use Cases:

Retrieve healthcare organization information
Access organization contact details and addresses
Query organizations by name or location
Support care coordination and referrals

Relationships to Other Resources:

Patient - Patients receive care from organizations
Practitioner - Healthcare providers work for organizations
Encounter - Healthcare encounters occur at organizations
Location - Organizations operate at physical locations

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",
          "display": "Healthcare Provider"
        }
      ]
    }
  ],
  "name": "string",
  "telecom": [
    {
      "system": "phone|fax|email|url",
      "value": "string",
      "use": "work|home"
    }
  ],
  "address": [
    {
      "use": "work|home|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/system-access/v2/{tenant-id}/Organization/org-123 \
    -H "Accept: application/fhir+json"

GET /Organization/{id}

Example Request
curl -X GET https://fhirtest.netsmartcloud.com/payer/system-access/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`
`name`	string	No	Organization name (partial match)	`name=Hospital`
`_lastUpdated`	date	No	Only return resources which were last updated as specified by the given range	`_lastUpdated=ge2023-01-01`
`_revinclude`	special	No	Include Provenance resource(s) that reference the matched search results. Allowed: "Provenance:target"	`_revinclude=Provenance:target`

Common Search Patterns

Find organizations by name:

GET /Organization?name=Hospital&_count=10

Search by city:

GET /Organization?address-city=Sacramento

Find by postal code:

GET /Organization?address-postalcode=95814

Search by state:

GET /Organization?address-state=CA&_count=20

Examples

Request Examples

Production
Preview

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

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

Search by postal code
curl -X POST https://fhir.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Organization/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "address-postalcode=95814"

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

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

Search by postal code
curl -X POST https://fhirtest.netsmartcloud.com/payer/system-access/v2/{tenant-id}/Organization/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "address-postalcode=95814"

Response Examples

Successful Search Response

Organization Search Bundle
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "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": "prov",
          "display": "Healthcare Provider"
        }
      ]
    }
  ],
  "name": "Bay Area Medical Center",
  "telecom": [
    {
      "system": "phone",
      "value": "(415) 555-0199",
      "use": "work"
    },
    {
      "system": "url",
      "value": "https://www.bayareamedical.com",
      "use": "work"
    }
  ],
  "address": [
    {
      "use": "work",
      "line": ["456 Medical Plaza", "Suite 100"],
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US"
    }
  ]
}

Empty Result Set

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

Integration Patterns

Common Workflows

1. Organization Lookup for Patient Care

# Step 1: Search for organization by name
GET /Organization?name=Hospital&_count=10

# Step 2: Get specific organization details
GET /Organization/org-123

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

2. Geographic Organization Search

# Step 1: Search by city and state
GET /Organization?address-city=Sacramento&address-state=CA

# Step 2: Narrow by postal code
GET /Organization?address-postalcode=95814

# Step 3: Get organization contact information
GET /Organization/org-456

Patient - Patients receive care from organizations
Practitioner - Healthcare providers work for organizations
Encounter - Healthcare encounters occur at organizations
Location - Organizations operate at physical locations

Include Parameters

Use _include and _revinclude to fetch related resources:

# Get organization with provenance information
GET /Organization?name=Hospital&_revinclude=Provenance:target

# Get organizations with recent updates
GET /Organization?_lastUpdated=ge2023-01-01&_count=5

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​