The FHIR R4 Organization resource defines entities responsible for providing, managing, or paying for healthcare services. This includes hospitals, clinics, health systems, payers, and other administrative or operational entities. In Health Gorilla, Organization is often referenced by PractitionerRole, Location, and Encounter resources.
Use Cases
- Identify the facility or organization associated with a provider
- Filter encounters or locations by managing organization
- Display organization contact and address information
typeis a required search parameter.Every Organization search must include a
typetoken in the formsystem|code. See Supportedtypecode systems for accepted values. Requests that omit the system (for example,?type=ins) are rejected.
Base URLs
- Production: https://api.healthgorilla.com/fhir/R4/Organization
- Sandbox: https://sandbox.healthgorilla.com/fhir/R4/Organization
Authentication
All requests require OAuth 2.0 authentication using a Bearer Token. Unauthorized requests return 401 Unauthorized responses.
Required Scopes
organization.readfor GETorganization.writefor POST, PUT, DELETE
For more information, go to: OAuth 2.0 Authentication.
Supported Methods
| Method | Operation | Description |
|---|---|---|
GET | Read Organization | Retrieves a specific Organization record by its FHIR ID. |
GET | Search Organization | Searches for Organization records using supported parameters. |
POST | Create Organization | Submits a new Organization record to the Health Gorilla FHIR server. |
PUT | Update Organization | Updates an existing Organization record by full resource replacement. |
DELETE | Delete Organization | Removes an existing Organization record from the system by full deletion. |
Search Parameters
Organization supports two search forms, and a request must use one of them:
- A directory search anchored on
type, optionally narrowed by name, address, or distance. - A hierarchy search on
partof.
There is no unqualified Organization search.
| Parameter | Required | Description |
|---|---|---|
type | Required in the directory search | The kind of organization to return. |
partof | Required in the hierarchy search | Returns the organizations belonging to the given parent, as Organization/{id}. |
name | No | Filters on the organization name. |
address-state | No | Filters on the state in the organization address. |
address-city | No | Filters on the city in the organization address. |
address-postalcode | No | Filters on the postal code in the organization address. |
near-distance | No | Limits results to the given distance from the searched location. |
_offset | No | Skips the given number of results. |
_tag | No | Filters on meta.tag. |
_security | No | Filters on meta.security. |
Filter on the discrete address-state, address-city, and address-postalcode parameters. A combined address parameter isn't supported.
Supported type Code Systems
type Code SystemsThe type search parameter is required and must include both the code system URL and the code, joined by a pipe (system|code). Health Gorilla accepts three code systems for R4 Organization.
| Code System URL | Codes | Use it to find… |
|---|---|---|
http://terminology.hl7.org/CodeSystem/organization-type | prov, dept, team, ins, govt, pay, other | Healthcare providers, payers/insurers, and other standard FHIR organization categories. |
https://www.healthgorilla.com/fhir/organization-type | PR, PRL, F, IP, CW, CQ, EHEX, HGHIN, QHIN | Health Gorilla–specific organization types — practices, practice locations, insurance providers, and network providers (Carequality, eHEX, QHIN). |
https://www.healthgorilla.com/facility-type | Any FacilityType value (for example, DiagnosticLaboratories, RadiologyImaging, Hospitals) | A specific facility type within Health Gorilla's catalog. |
Searches without the code system URL fail.R4 does not accept bare codes.
?type=insand?type=provreturn an error because the server cannot determine which code system the code belongs to. Always supply thesystem|code.
Search Examples
In type tokens, the pipe character (|) must be URL-encoded as %7c.
Example 1: Find a LabCorp provider organization
GET https://api.healthgorilla.com/fhir/R4/Organization?
type=http://terminology.hl7.org/CodeSystem/organization-type%7cprov
&name=labcorpExample 2: Find Cigna as an insurance company
GET https://api.healthgorilla.com/fhir/R4/Organization?
type=http://terminology.hl7.org/CodeSystem/organization-type%7cins
&name=Cigna
The shorter form?type=ins&name=Cignadoes not return results because thetypetoken is missing its code system URL.
Example 3: Find a Health Gorilla practice in Sunnyvale
GET https://api.healthgorilla.com/fhir/R4/Organization?
type=https://www.healthgorilla.com/fhir/organization-type%7cPR
&address-city=Sunnyvale
&name=HealthCenterExample 4: Find a diagnostic laboratory by name
GET https://api.healthgorilla.com/fhir/R4/Organization?
type=https://www.healthgorilla.com/facility-type%7cDiagnosticLaboratories
&name=QuestResource Attributes
| Attribute | Description | Example Values | FHIR Data Type | Required |
|---|---|---|---|---|
id | Unique FHIR ID for the organization | org-123456 | id | Yes |
name | Name of the organization | Health Gorilla | string | Yes |
identifier | Unique business identifiers (NPI, TIN, etc.) | NPI: 1234567890 | Identifier[] | No |
type | Type of organization | prov (healthcare provider) | CodeableConcept[] | No |
active | Whether the organization record is currently active | true, false | boolean | No |
telecom | Contact information (e.g., phone, fax, email) | 408-555-1234 | ContactPoint[] | No |
address | Physical or mailing address | 123 Wellness Way, Sunnyvale, CA | Address[] | No |
partOf | Parent organization, if this is a branch or subdivision | Organization/{id} | Reference(Organization) | No |
endpoint | Reference to technical endpoints for services like Direct | Endpoint/{id} | Reference(Endpoint) | No |
Webhooks
Organization resources are not typically included in webhook notifications directly, but they are commonly referenced by webhook-triggering resources such as Encounter, PractitionerRole, and Location. For more information, go to: Webhooks & Polling.
Error Handling
All Organization operations follow standard Health Gorilla error handling, including use of FHIR OperationOutcome for structured responses. For more information, go to: Error Handling.