API Reference

Organization

The FHIR STU3 Organization resource is used to obtain information about Practices, Laboratories, Hospitals and other facilities that exist in the Health Gorilla catalog.

FHIR Resource: Organization https://www.hl7.org/fhir/organization.html

Supported Attributes

Field NameComments
active
typeThere are several value sets supported:
https://www.hl7.org/fhir/valueset-organization-type.html
 https://www.healthgorilla.com/fhir/ValueSet/facility-type
* https://www.healthgorilla.com/fhir/ValueSet/organization-type
name
telecom
address
partOfLink to the department or to the parent Organization.
https://api.healthgorilla.com/fhir/Organization

FHIR Operations

The following operations are currently supported:

1. Read

HTTP RequestMethodAction
/Organization/{ID}GETRetrieve organization by ID

2. Search

HTTP RequestMethodAction
/Organization?[parameter={value}]GETRetrieve Organizations by the specified search criteria

Search Parameters:

NameTypeDescription
typeTokenCode for the type of organization.
namestringPortion of the organization's name or alias.
address-statestringState in the organization's address.
address-citystringCity in the organization's address.
address-postalcodestringPostal code in the organization's address.
near-distanceQuantityMiles
ordering-enabledtokenOrdering-enabled property. Use to get only organizations that support ordering, e.g. diagnostic laboratories. These organizations can be referenced in 'performer' attribute of the RequestGroup resource.
_countnumberPositive integer. If specified then the server will not return more than _count results.
_offsetnumberPositive integer. Specifies the position to return search results from.

Examples:

2.1 Search laboratories with name LabCorp that support ordering:

https://api.healthgorilla.com/fhir/Organization?
type=http://hl7.org/fhir/organization-type|prov&name=LabCorp
&ordering-enabled=true

2.2 Search healthcare practices in Sunnyvale:

https://api.healthgorilla.com/fhir/Organization?
type=https://www.healthgorilla.com/fhir/organization-type|PR&address-city=Sunnyvale
&name=HealthCenter

2.3 Search AETNA insurance companies in California

https://api.healthgorilla.com/fhir/Organization?
type=http://hl7.org/fhir/organization-type|ins&name=AETNA&address-state=CA
&_count=15

3. Create

HTTP RequestMethodAction
/OrganizationPOSTCreates a new organization

The following attributes are required to create a new organization:

NameDetails
activetrue
nameName of the organization
addressAddress of the organization
typeOnly a few types are supported. See below.

Only the following organization types are supported:

Code SystemCodeDescription
http://hl7.org/fhir/organization-typeinsInsurance Provider
https://www.healthgorilla.com/fhir/organization-typeIPInsurance Provider
http://terminology.hl7.org/CodeSystem/organization-typeprovHealthcare Provider

3.1 Create Insurance Provider

The Organization API can be used to create insurance providers inside of Health Gorilla.

Examples

Create new Insurance Provider
{ 
   "resourceType":"Organization",
   "active":true,
   "type":[ 
      { 
         "coding":[ 
            { 
               "system":"http://hl7.org/fhir/organization-type",
               "code":"ins",
               "display":"Insurance Company"
            }
         ],
         "text":"Insurance Company"
      }
   ],
   "name":"HealthGorilla",
   "telecom":[ 
      { 
         "system":"phone",
         "value":"1 (844) 446-7455"
      }
   ],
   "address":[ 
      { 
         "line":[ 
            "185 N Wolfe Rd"
         ],
         "city":"Sunnyvale",
         "state":"CA",
         "postalCode":"94085",
         "country":"USA"
      }
   ]
}
An attempt to create duplicate

Health Gorilla does not allow duplicates, so if the supplied organization already exists, then the operation fails with an error.

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "duplicate",
            "details": {
                "text": "The supplied record duplicates the existing one."
            },
            "diagnostics": "Failed to create duplicate."
        }
    ]
}

You can find the identifier of an existing resource in 'Existing-Resource-Id' header.

3.2 Creating a Tenant

The Organization FHIR API can be used to create tenants inside of Health Gorilla. This workflow can be utilized for users who maintain multiple tenants inside of Health Gorilla. An example would be a multi-practice health company or provider group. To create a tenant via the Organization endpoint, the following requirements must be met.

  1. A main, or parent, tenant must be created by a Health Gorilla operations team member.
  2. An IPA facility must be created inside of the parent tenant by a Health Gorilla team member. This IPA facility is reference by a unique identifier in the format ‘f-#########’. This facility ID will be provided to you by a Health Gorilla team member.
  3. The sub of the JWT used to retrieve an access token must be the login or email of an admin user in the parent tenant.
  4. The multi_tenant scope must be included in the request for an access token.
  5. The facility ID must be included in the Organiziation payload POST to the Organization API.

Once these requirements are met and an access token has been retrieved, a POST can be made to the Organization API with the following attributes:

AttributeRequiredNotes
metaYesThis field will contain a profile attribute. The value will always be: https://api.healthgorilla.com/fhir/StructureDefinition/multi-tenant-subtenant
extensionYesThe extension attribute will contain the facility ID representing the IPA facility.
activeYesValue will be true when creating a tenant
nameYesThe name of the practice/tenant
addressYesThe address object contains the address of the practice
telecomNoOptional field containing the phone number of the practice
typeYesThe type object contains the type of organization that will be created. When creating a Tenant, the value will always be prov.

Examples

Creating a Tenant


{
    "resourceType": "Organization",
    "meta": {
        "profile": [
            "https://api.healthgorilla.com/fhir/StructureDefinition/multi-tenant-subtenant"
        ]
    },
    "extension": [
        {
            "url" : "https://www.healthgorilla.com/fhir/StructureDefinition/multi-tenant",
            "valueId" : "f-f3333331ddd9ab1678ff97e6"
        }
    ],
    "active": true,
    "name": "Acme Provider Office",
    "address": [
        {
            "line": "545 Green St",
            "city": "New York",
            "state": "NY",
            "postalCode": "11134",
            "country": "USA"
        }
    ],
    "telecom": [
        {
            "system": "phone",
            "value": "1 (111) 111-1111"
        }
    ],
    "type": [
        {
            "coding": [
                {
                    "system": "http://terminology.hl7.org/CodeSystem/organization-type",
                    "code": "prov",
                    "display": "Healthcare Provider"
                }
            ],
            "text": "Healthcare Provider"
        }
    ]
}

4. Update

HTTP RequestMethodAction
/Organization/{ID}PUTUpdates the Organization resource or creates a new one.

📘

Restrictions

  • You can only update local Organizations (insurance providers) that you created.
  • You can't modify an existing insurance provider to become a duplicate of another insurance provider. The endpoint rejects such requests.

5. Delete

HTTP RequestMethodAction
/Organization/{ID}DELETEDeletes the Organization resource

📘

Restrictions

  • You can only delete local insurance providers.