FHIR RESTful API (Part 2)

Overview

Observation

The Observation resource describes measurements and simple assertions made about a patient, device or other subject.

FHIR Resource: Observation https://www.hl7.org/fhir/observation.html

Health Gorilla supports the following categories of Observation:

System	Code	Display
http://hl7.org/fhir/observation-category	laboratory	Laboratory
http://hl7.org/fhir/observation-category	imaging	Imaging
http://hl7.org/fhir/observation-category	vital-signs	Vital Sign
http://hl7.org/fhir/observation-category	social-history	Social History
https://www.healthgorilla.com/fhir/observation-category	functional-status	Functional Status

The following attributes are supported:

Name	Comment
status
category
identifier
code	LOINC preferred
subject	Patient
effective
issued
performer	Reference to Practitioner Reference to Patient supported for Vital Signs, Social History, and Functional Status categories.
value
interpretation
comment
referenceRange
related	Observation, DeviceUseStatement
http://hl7.org/fhir/StructureDefinition/event-partOf	DiagnosticReport, Observation

https://api.healthgorilla.com/fhir/Observation

FHIR Operations

The following operations are currently supported:

List of available operations per category:


Laboratory, Imaging	Read, Search, Create
Vital Sign	Read, Search, Create, Update, Delete
Social History	Read, Search, Create, Update, Delete
Functional Status	Read, Search, Create, Update, Delete

1. Read

HTTP Request	Method	Action
/Observation/{ID}	GET	Retrieve Observation resource by ID

2. Search

HTTP Request	Method	Action
/Observation?[parameter={value}]	GET	Retrieve Observation resources by the specified search criteria

Parameters:

Key	Type	Description
patient	Reference	Patient resource logical identifier. Required.
category	Token	Observation category (see: http://hl7.org/fhir/codesystem-observation-category.html). Required.
_lastUpdated	Date
_offset	Number
_count	Number

Examples:

2.1. Retrieve Laboratory Observations by patient

https://api.healthgorilla.com/fhir/Observation?
category=http://hl7.org/fhir/observation-category|laboratory
&patient=8063965523692105bfc35def

2.2. Retrieve Vital Signs by patient

https://api.healthgorilla.com/fhir/Observation?
category=http://hl7.org/fhir/observation-category|vital-signs
&patient=8063965523692105bfc35def

2.3. Retrieve Social History by patient

https://api.healthgorilla.com/fhir/Observation?
category=http://hl7.org/fhir/observation-category|social-history
&patient=8063965523692105bfc35def

2.4. Retrieve Functional Status by patient

https://api.healthgorilla.com/fhir/Observation?
category=https://www.healthgorilla.com/fhir/observation-category|functional-status
&patient=8063965523692105bfc35def

2.5. Search records updated saince March 2019

https://api.healthgorilla.com/fhir/Observation?
category=http://hl7.org/fhir/observation-category|vital-signs
&_lastUpdated=gt2019-03
&_offset=0
&_count=5

2.6. Retrieve records for the given patient updated in 2018

https://api.healthgorilla.com/fhir/Observation?
category=http://hl7.org/fhir/observation-category|vital-signs
&patient=8063965523692105bfc35def
&_lastUpdated=2018

3. Create

HTTP Request	Method	Action
/Observation	POST	Creates Observation resource

The following attributes are required for Vital Sign:

Name	Details
subject
status
related	Observation (code, value)

The following attributes are required for Social History:

Name	Details
subject
status
code
value

The following attributes are required for Functional Status:

Name	Details
subject
status
code
related	DeviceUseStatement

Example:

3.1. Add Vital Sign

<Observation xmlns="http://hl7.org/fhir">
    <meta>
        <profile value="http://hl7.org/fhir/StructureDefinition/vitalspanel"/>
    </meta>
    <contained>
        <Observation xmlns="http://hl7.org/fhir">
            <id value="1"/>
            <status value="unknown"/>
            <category>
                <coding>
                    <system value="http://hl7.org/fhir/observation-category"/>
                    <code value="vital-signs"/>
                    <display value="Vital Signs"/>
                </coding>
            </category>
            <code>
                <coding>
                    <system value="http://loinc.org"/>
                    <code value="8310-5"/>
                    <display value="Body temperature"/>
                </coding>
                <coding>
                    <system value="http://snomed.info/sct"/>
                    <code value="386725007"/>
                    <display value="Body temperature"/>
                </coding>
            </code>
            <subject>
                <reference value="Patient/03db4352ee0190ad5e9e6748"/>
                <display value="Homer Simpson"/>
            </subject>
            <valueQuantity>
                <value value="36.5"/>
                <unit value="C"/>
                <system value="http://unitsofmeasure.org"/>
                <code value="Cel"/>
            </valueQuantity>
        </Observation>
    </contained>
    <status value="unknown"/>
    <category>
        <coding>
            <system value="http://hl7.org/fhir/observation-category"/>
            <code value="vital-signs"/>
            <display value="Vital Signs"/>
        </coding>
    </category>
    <code>
        <coding>
            <system value="http://loinc.org"/>
            <code value="85353-1"/>
            <display value="Vital Signs Panel"/>
        </coding>
    </code>
    <subject>
        <reference value="Patient/03db4352ee0190ad5e9e6748"/>
        <display value="Homer Simpson"/>
    </subject>
    <effectiveDateTime value="2018-06-01"/>
    <performer>
        <reference value="Practitioner/ceda4352e8f6405dd2e42f09"/>
        <display value="John Doe"/>
    </performer>
    <related>
        <type value="has-member"/>
        <target>
            <reference value="#1"/>
        </target>
    </related>
</Observation>

3.2. Add Social History

<Observation xmlns="http://hl7.org/fhir">
    <status value="unknown"/>
    <category>
        <coding>
            <system value="http://hl7.org/fhir/observation-category"/>
            <code value="social-history"/>
            <display value="Social History"/>
        </coding>
    </category>
    <code>
        <coding>
            <system value="http://snomed.info/sct"/>
            <code value="160573003"/>
            <display value="Alcohol Use"/>
        </coding>
        <text value="port wine, red"/>
    </code>
    <subject>
        <reference value="Patient/03db4352ee0190ad5e9e6748"/>
        <display value="Homer Simpson"/>
    </subject>
    <effectivePeriod>
        <start value="2017-12-06"/>
        <end value="2018-09-20T01:30:00+03:00"/>
    </effectivePeriod>
    <performer>
        <reference value="Practitioner/ceda4352e8f6405dd2e42f09"/>
        <display value="John Doe"/>
    </performer>
    <valueCodeableConcept>
        <coding>
            <display value="Only 10 old port wine"/>
        </coding>
    </valueCodeableConcept>
    <comment value="This began just after the trip to Lisboa."/>
</Observation>

3.3. Add Laboratory Observation

{ 
   "resourceType":"Observation",
   "contained":[ 
      { 
         "id":"1",
         "resourceType":"Patient",
         "identifier":[ 
            { 
               "use":"usual",
               "type":{ 
                  "coding":[ 
                     { 
                        "system":"http://terminology.hl7.org/CodeSystem/v2-0203",
                        "code":"MR",
                        "display":"Medical record number"
                     }
                  ],
                  "text":"Medical record number"
               },
               "system":"https://www.healthgorilla.com",
               "value":"e20f61506d170a4423bb35a0"
            }
         ]
      }
   ],
   "status":"final",
   "category":{ 
      "coding":[ 
         { 
            "code":"laboratory",
            "system":"http://hl7.org/fhir/observation-category"
         }
      ],
      "text":"Laboratory"
   },
   "code":{ 
      "coding":[ 
         { 
            "code":"3043-7",
            "system":"http://loinc.org"
         }
      ],
      "text":"Triglycerides"
   },
   "issued":"2017-03-18T00:00:00Z",
   "referenceRange":[ 
      { 
         "high":{ 
            "code":"mg/dL",
            "system":"http://unitsofmeasure.org",
            "unit":"mg/dL",
            "value":250
         },
         "low":{ 
            "code":"mg/dL",
            "system":"http://unitsofmeasure.org",
            "unit":"mg/dL",
            "value":10
         },
         "text":"10 to 250 mg/dL"
      }
   ],
   "valueQuantity":{ 
      "code":"mg/dL",
      "system":"http://unitsofmeasure.org",
      "unit":"mg/dL",
      "value":86
   },
   "subject":{ 
      "display":"James Ellroy",
      "reference":"#1"
   }
}

4. Update

HTTP Request	Method	Action
/Observation/{ID}	PUT	Updates Observation resource

The following attributes are immutable for Vital Sign:

Name	Details
patient
performer

The following attributes are immutable for Social History:

Name	Details
patient
performer
code

The following attributes are immutable for Functional Status:

Name	Details
patient
performer

5. Delete

HTTP Request	Method	Action
/Observation/{ID}	DELETE	Deletes Observation resource

Procedure

The Procedure resource describes an action that is or was performed on a patient. This can be a physical intervention like an operation, or less invasive like counseling or hypnotherapy.

FHIR Resource: Procedure https://www.hl7.org/fhir/procedure.html
The following attributes are supported:

Name	Comment
status
category
code
subject	Patient
performed
performer
location
usedReference	Medication, Device
bodySite
resonCode
reasonReference
outcome
followUp
partOf	ProcedureRequest
note
https://www.healthgorilla.com/fhir/StructureDefinition/record-recorder	Recorder (Participant)
http://hl7.org/fhir/StructureDefinition/procedure-method	CodeableConcept

https://api.healthgorilla.com/fhir/Procedure

FHIR Operations

The following operations are currently supported:

1. Read

HTTP Request	Method	Action
/Procedure/{ID}	GET	Retrieve Procedure resource by ID

2. Search

HTTP Request	Method	Action
/Procedure?[parameter={value}]	GET	Retrieve Procedure resources by the specified search criteria

Parameters:

Key	Type	Description
patient	Reference	Patient Identifier
_lastUpdated	Date
_offset	Number
_count	Number

Examples:

2.1. Retrieve procedures by patient

https://api.healthgorilla.com/fhir/Procedure?patient=8063965523692105bfc35def

2.2. Search records updated since March 2019

https://api.healthgorilla.com/fhir/Procedure?_lastUpdated=gt2019-03&_offset=0&_count=5

2.3. Retrieve records for the given patient updated in 2018

https://api.healthgorilla.com/fhir/Procedure?patient=8063965523692105bfc35def&_lastUpdated=2018

3. Create

HTTP Request	Method	Action
/Procedure	POST	Creates Procedure resource

The following attributes are required:

Name	Details
subject
code

4. Update

HTTP Request	Method	Action
/Procedure/{ID}	PUT	Updates Procedure resource

The following attributes are immutable:

Name	Details
patient
recorder
code

5. Delete

HTTP Request	Method	Action
/Procedure/{ID}	DELETE	Deletes Procedure resource

ProcedureRequest

The ProcedureRequest resource contains record of a request for diagnostic investigations, treatments, or operations to be performed.

FHIR Resource: ProcedureRequest https://www.hl7.org/fhir/procedurerequest.html

The following attributes are supported:

Name	Comment
identifier	ACSN (Lab Reference ID)
requisition
status
intent
subject	Patient
priority
category
performer	Laboratory (Organization)
code
authoredOn
reasonCode	Diagnosis
supportingInfo	AOE
specimen
note
http://hl7.org/fhir/StructureDefinition/procedurerequest-authorizedBy	Author (Practitioner)

https://api.healthgorilla.com/fhir/ProcedureRequest

FHIR Operations

The following operations are currently supported:

1. Read

HTTP Request	Method	Action
/ProcedureRequest/{ID}	GET	Retrieve ProcedureRequest resource by ID

2. Search

HTTP Request	Method	Action
/ProcedureRequest?[parameter={value}]	GET	Retrieve ProcedureRequest resources by the specified search criteria

Parameters:

Key	Type	Description
patient	Reference	Patient Identifier
requisition	Token	Requisition Identifier
_lastUpdated	Date	Can be used when looking up records for a patient.

Examples:

2.1. Retrieve ProcedureRequest resources by patient and date

https://api.healthgorilla.com/fhir/Procedure?
patient=8063965523692105bfc35def
&_lastUpdated=2018-07

2.2. Retrieve ProcedureRequest resources by order ID

https://api.healthgorilla.com/fhir/Procedure?requisition=a5606c5b8998949c08f49526

ReferralRequest

Used to record and send details about a request for referral service or transfer of a patient to the care of another provider or provider organization.

FHIR Resource: ReferralRequest http://hl7.org/fhir/stu3/referralrequest.html

The following profile is required:

https://healthgorilla.com/fhir/StructureDefinition/hg-referral

https://api.healthgorilla.com/fhir/ReferralRequest

The following attributes are supported:

Name	Comment
identifier
status
intent	order
subject	Patient
authoredOn
requester
recipient	Single recipient only. Practitioner or Organization
https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-recipient	Recipient Practitioner and Organization.
note
reasonCode	ICD10
supportingInfo	DiagnosticReport, DocumentReference, Binary
https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-deliveryOptions
https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-reply

FHIR Operations

The following operations are currently supported:

1.Read

HTTP Request	Method	Action
/ReferralRequest/{ID}	GET	Retrieve ReferralRequest resource by ID

2.Search

HTTP Request	Method	Action
/ReferralRequest?[parameter={value}]	GET	Retrieve ReferralRequest resources by the specified search criteria

Parameters:

Name	Type	Description
patient	Reference	Patient Identifier
identifier	Token	External Identifier
status	Token
_lastUpdated	Date	gt, ge, eq
_offset	Number	Default is 0
_count	Number	Default is 100
_include		Use to include linked Patient and related Observations into result Bundle. https://www.hl7.org/fhir/STU3/search.html#include

Available values for include directive:

Include	Criteria	Resource
_include	ReferralRequest:subject	Patient
_include	ReferralRequest:requester.agent	Practitioner
_include	ReferralRequest:requester.onBehalfOf	Organization
_include	ReferralRequest:recipient	Practitioner and(or) Organization
_include	ReferralRequest:supportingInfo	DiagnosticReport, DocumentReference

Examples:

2.1. Get referral with Health Gorilla identifier '0cb02b5bb9e7f9318af8dd67', include recipient and supported documents.

https://api.healthgorilla.com/fhir/Referralrequest
?identifier=https://www.healthgorilla.com|0cb02b5bb9e7f9318af8dd67
&_include=ReferralRequest:recipient
&_include=ReferralRequest:supportingInfo

2.2. Retrieve Referrals by patient updated in March 2020

https://api.healthgorilla.com/fhir/ReferralRequest
?patient=8063965523692105bfc35def
&_lastUpdated=eq2020-03

3. Download PDF

You can generate a PDF copy of the record using the following request:

HTTP Request	Method	Action
/ReferralRequest/{ID}/$pdf	GET	Generate PDF

The result contains a link to a Binary resource (PDF) that can be downloaded.

Example:

https://api.healthgorilla.com/fhir/ReferralRequest/8063965523692105bfc35def/$pdf

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "url",
            "valueString": "http://api.healthgorilla.com/fhir/Binary/bf5e745ba2f573534d447686"
        },
        {
            "name": "contentType",
            "valueString": "application/pdf"
        },
        {
            "name": "size",
            "valuePositiveInt": 13081
        }
    ]
}

4. Create

You can send a new referral request to the specified practitioner or organization.

HTTP Request	Method	Action
/ReferralRequest	POST	Submit new referral

You can send referral to

existing HealthGorilla practitioner
any practitioner by fax or email
existing HealthGorilla organization

RequestGroup

The RequestGroup resource represents a group of related requests that can be used to capture intended activities that have inter-dependencies. In Health Gorilla this resource used to describe a laboratory/radiology order.

FHIR Resource: RequestGroup https://www.hl7.org/fhir/requestgroup.html

The following profile is required:

https://healthgorilla.com/fhir/StructureDefinition/hg-order

The following attributes are supported:

Name	Comment
identifier	ACSN (Lab Reference ID), HG ID
requisition
status
intent
subject	Patient
priority
author	Practitioner
authoredOn
action	ProcedureRequest
note
https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-authorizedBy	Author(Organization)
https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-account	Account
https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-performer	Performer(Organization)
https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-requester	Requester
https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-reasoncode	Diagnoses
https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-specimen	Specimen
https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-deliveryOptions	Delivery Options (location, method, electronic)
https://www.healthgorilla.com/fhir/StructureDefinition/performer-location	Performer Location (Location)

https://api.healthgorilla.com/fhir/RequestGroup

FHIR Operations

The following operations are currently supported:

1. Read

HTTP Request	Method	Action
/RequestGroup/{ID}	GET	Retrieve RequestGroup resource by ID

2. Search

HTTP Request	Method	Action
/RequestGroup?[parameter={value}]	GET	Retrieve RequestGroup resources by the specified search criteria

Parameters:

Key	Type	Description
patient	Reference	Patient Identifier
identifier	Token	External Identifier
_lastUpdated	Date
_offset	Number
_count	Number

Examples:

2.1. Retrieve Order by ID

https://api.healthgorilla.com/fhir/RequestGroup/a5606c5b8998949c08f49526

2.2. Retrieve Order by requisition ID

https://api.healthgorilla.com/fhir/RequestGroup?identifier=https://www.healthgorilla.com| a5606c5b8998949c08f49526

2.3. Retrieve Orders by Lab Reference ID

https://api.healthgorilla.com/fhir/RequestGroup?performer={{facility_id}}&identifier={{lab_reference_id}}

2.4. Retrieve Orders by patient and date

https://api.healthgorilla.com/fhir/RequestGroup?patient=8063965523692105bfc35def&_lastUpdated=2018-07

3. Create

Clients can submit new orders. Visit Diagnostic Network Guide for more details

4. Download PDF

You can generate a PDF copy of the record using the following request:

HTTP Request	Method	Action
/RequestGroup/{ID}/$pdf	GET	Generate PDF

The result contains a link to a Binary resource (PDF) that can be downloaded.

Example:

https://api.healthgorilla.com/fhir/RequestGroup/8063965523692105bfc35def/$pdf

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "url",
            "valueString": "http://api.healthgorilla.com/fhir/Binary/bf5e745ba2f573534d447686"
        },
        {
            "name": "contentType",
            "valueString": "application/pdf"
        },
        {
            "name": "size",
            "valuePositiveInt": 13081
        }
    ]
}

Instant Message

An InstantMessage resource is used to describe a message between persons and organizations in HealthGorilla Application. A message is a composite object that contains a sender and recipients, a subject, a message body and attachments. Users may send messages to (and receive from) physicians, practice staff, patients, healthcare organizations.

A InstantMessage is designed to describe HealthGorilla Secure Messages and should not be used for other purposes.
A InstantMessage can contain DiagnosticReport, RequestGroup, DocumentReference, ReferralRequest as attachments.

https://api.healthgorilla.com/fhir/InstantMessage

FHIR Operations

The following operations are currently supported:

1. Read

HTTP Request	Method	Action
/InstantMessage/{ID}?_format=json	GET	Get message by ID

2. Search

HTTP Request	Method	Action
/InstantMessage?[parameter={value}]	GET	Returns DirectMessage resources matching the filter specified as a parameter

Parameters:

Key	Type	Description
direction	Token	OUT for outgoing messages and IN for incoming
identifier	Token	InstantMessage identifier
_lastUpdated	Date	Return InstantMessage resources modified after the specified date. E.g. gt2019-09-05

Examples:

2.1 Retrieve all incoming messages received starting from 09/05/2019

https://api.healthgorilla.com/fhir/InstantMessage?
direction=IN
&_lastUpdated=gt2019-09-05
&_format=json

2.2 Retrieve InstantMessage resource with identifier of 35f3d35d12aa8d93dd9953c0

https://api.healthgorilla.com/fhir/InstantMessage?
identifier=https://www.healthgorilla.com|35f3d35d12aa8d93dd9953c0
&_format=json

Electronic Fax

If your organization account is setup with electronic fax in Health Gorilla then you can send and receive faxes using FaxMessage resource.

https://api.healthgorilla.com/fhir/FaxMessage

FHIR Operations

The following operations are currently supported:

1. Read

HTTP Request	Method	Action
/FaxMessage/{ID}?_format=json	GET	Get fax message by ID

2. Search

HTTP Request	Method	Action
/FaxMessage?[parameter={value}]	GET	Returns FaxMessage resources matching the filter specified as parameters

Parameters:

Key	Type	Description
direction	Token	OUT for outgoing faxes and IN for incoming
identifier	Token	FaxMessage identifier
_lastUpdated	Date	Return FaxMessage resources that modified after the specified date. E.g. gt2019-09-05

Examples:

2.1 Retrieve all incoming fax messages received starting 09/05/2019

https://api.healthgorilla.com/fhir/FaxMessage?
direction=IN
&_lastUpdated=gt2019-09-05
&_format=json

2.2 Retrieve FaxMessage resource with identifier of 35f3d35d12aa8d93dd9953c0

https://api.healthgorilla.com/fhir/FaxMessage?
identifier=https://www.healthgorilla.com|35f3d35d12aa8d93dd9953c0
&_format=json

3. Send

HTTP Request	Method	Action
/FaxMessage	POST	Creates a new FaxMessage resource with OUT direction and sends corresponding fax message to recipients

Example

Send electronic fax that is:

originating from Organization with identifier d5da4352af2201ace56ca725 (subject to access rights validation) and
organization's location with identifier 931490546b89416ed64ff6a4.
use "(000) 000-1000" as your fax number (should match one of fax numbers assigned to organization)
to "(000) 000-0001" as fax recipient
consists of example.pdf contents and
of Document stored in Health Gorilla with identifier bfaf6a5b9e46e25e949e211b

{
    "resourceType": "FaxMessage",
    "sender": {
        "organization": {
            "reference": "Organization/tl-d5da4352af2201ace56ca725-931490546b89416ed64ff6a4",
            "display": "Dr. Doe Practice"
        },
        "faxNumber": "(000) 000-1000"
    },
    "recipient": [
        {
            "faxNumber": "(000) 000-0001"
        }
    ],
    "title": "My Fax",
    "content" : {
    	"text" : "Sample"
    },
    "attachment": [
        {
            "file": {
                "contentType": "application/pdf",
                "data": "<BASE64 encoded contents of example.pdf>",
                "title": "example.pdf"
            }
        },
        {
            "reference": {
                "reference": "DocumentReference/bfaf6a5b9e46e25e949e211b"
            }
        }
    ]
}

In order to get notified of faxes that could not be delivered by Health Gorilla to recipients (e.g. if recipient's phone line is busy or fax number is incorrect) you can register a Subscription resource.

Failed fax message example:

{
	"fullUrl": "https://www.healthgorilla.com/fhir/FaxMessage/7450955f0b8602fe0e0c706c",
	"resource": {
		"resourceType": "FaxMessage",
		"id": "7450955f0b8602fe0e0c706c",
		"meta": {
			"lastUpdated": "2020-10-25T10:20:56.604+00:00",
			"profile": [
				"http://healthgorilla.com/fhir/Profile/FaxMessage"
			]
		},
		"identifier": [
			{
				"system": "https://www.healthgorilla.com",
				"value": "7450955f0b8602fe0e0c706c"
			}
		],
		"sentOn": "2020-10-25T10:20:38+00:00",
		"sender": {
			"practitioner": {
				"reference": "Practitioner/c5036153e4b3c9434ba3b23d",
				"display": "John Gorilla Doe, Ph. D. Psychology (F: (209) 290-3679)"
			},
			"organization": {
				"reference": "Organization/tl-e20f4150465d48754d810819-ea31545185c0556b53d81de9",
				"display": "San Jose Place & Place"
			},
			"faxNumber": "(209) 290-3679"
		},
		"recipient": [
			{
				"faxNumber": "(000) 000-0000",
				"deliveryFailed": true
			}
		],
		"title": "Test Fax",
		"content": {
			"text": "Some text here"
		},
		"attachment": [
			{
				"file": {
					"contentType": "application/pdf",
					"url": "https://www.healthgorilla.com/fhir/Binary/7851985f87824b8ed889991d",
					"size": 122014,
					"hash": "OTYyNTllMzEyMDZkNTlhZDhjY2I2YmE0NDIxOTUxYmQ=",
					"title": "fax.pdf"
				}
			},
			{
				"file": {
					"contentType": "application/pdf",
					"url": "https://www.healthgorilla.com/fhir/Binary/73212552bd2e9f27e907722a",
					"size": 38570,
					"hash": "YzA2N2JiYmQxM2Y2YjY0MDVhNmE4NWY2NzkwODUzYmQ=",
					"title": "example.pdf"
				}
			},
			{
				"reference": {
					"reference": "DiagnosticReport/ae8ea05e9e01ef7e9a3b9f8a"
				}
			},
			{
				"reference": {
					"reference": "DocumentReference/43e8e25ea1be726eccb14770"
				}
			}
		],
		"direction": {
			"coding": [
				{
					"system": "https://www.healthgorilla.com/fhir/message-direction",
					"code": "OUT",
					"display": "Outgoing"
				}
			],
			"text": "OUTGOING"
		}
	}
}

Successful fax message example:

{
	"fullUrl": "https://www.healthgorilla.com/fhir/FaxMessage/74f29f5f82cf31fc6af1b887",
	"resource": {
		"resourceType": "FaxMessage",
		"id": "74f29f5f82cf31fc6af1b887",
		"meta": {
			"lastUpdated": "2020-10-25T10:24:58.370+00:00",
			"profile": [
				"http://healthgorilla.com/fhir/Profile/FaxMessage"
			]
		},
		"identifier": [
			{
				"system": "https://www.healthgorilla.com",
				"value": "74f29f5f82cf31fc6af1b887"
			}
		],
		"sentOn": "2020-10-25T10:24:54+00:00",
		"sender": {
			"practitioner": {
				"reference": "Practitioner/c50d615de4bdc94d4bd3b23d",
				"display": "John Gorilla Doe, Ph. D. Psychology (F: (209) 290-3679)"
			},
			"organization": {
				"reference": "Organization/tl-e20f6150b65ddd7d3d810819-ea3124f1f3c059fb53d81de9",
				"display": "San Jose Place & Place"
			},
			"faxNumber": "(209) 290-3679"
		},
		"recipient": [
			{
				"organization": {
					"reference": "Organization/f-ea0f61f0cf3cf3e228091d8e",
					"display": "AdLabs"
				},
				"faxNumber": "000 000 0001"
			}
		],
		"title": "Test fax",
		"content": {
			"text": "Some text here"
		},
		"attachment": [
			{
				"file": {
					"contentType": "application/pdf",
					"url": "https://www.healthgorilla.com/fhir/Binary/7652050f6c608f04c307d164",
					"size": 26691,
					"hash": "ZjYyNzVjYjgxODk5Yjc0YTE5ZGE3NmZiYjVjZDhkMTY=",
					"title": "fax.pdf"
				}
			},
			{
				"reference": {
					"reference": "RequestGroup/749c7f5d77f80da7124269f4"
				}
			}
		],
		"direction": {
			"coding": [
				{
					"system": "https://www.healthgorilla.com/fhir/message-direction",
					"code": "OUT",
					"display": "Outgoing"
				}
			],
			"text": "OUTGOING"
		}
	}
}

Record Locator Service

The Record Locator Service (RLS) API provides a summary view for where the patient has received treatment and from whom. View the care organizations (e.g. hospitals, clinics) where the patient has received treatment, the labs or imaging centers where a patient has a result, and the providers that have been associated with the patient's care.

OAuth scope: user/Patient.read rls

Name	Method	Action
/List?[parameter={value}]	GET	Read organizations and providers involved in patient's treatment.

Parameters:

Key	Type	Parameter
patient	Reference
code	Token	Contains one or more comma-delimited RLS collection types.

Collection Types:

Code	Display	Description
careorganizations	Care Organizations	Where the patient has been treated. FHIR Resources: Organization
laborimaging	Lab or Imaging Center	Where the patient has received Diagnostic and Radiology results. FHIR Resources: Organization
providers	Providers	People who have been or are involved in the patient's care. FHIR Resources: Practitioner

Examples:

Return care organizations involved in the patient's care, laboratories and imaging centers that produces diagnostic reports for the specified patient.

https://api.healthgorilla.com/fhir/List?patient=03db4352ee0190ad5e9e6748&code=careorganizations,laborimaging

Clinical Notes

Health Gorilla allows developers to create new and import existing Clinical Notes using FHIR endpoints and resource profiles described in C-CDA on FHIR architecture.

See C-CDA on FHIR Implementation Guide http://hl7.org/fhir/us/ccda/index.html

Clinical notes support is based on two FHIR resources: Composition and Bundle

Composition http://hl7.org/fhir/stu3/composition.html
Bundle http://hl7.org/fhir/stu3/bundle.html

FHIR Composition is used to describe Clinical Note document itself and FHIR Bundle is used to pack all related data into one message.

The following profiles are supported:

Name	URI
Discharge Summary	http://hl7.org/fhir/us/ccda/StructureDefinition/CCDA-on-FHIR-Discharge-Summary
Progress Note	http://hl7.org/fhir/us/ccda/StructureDefinition/CCDA-on-FHIR-Progress-Note
History and Physical	http://hl7.org/fhir/us/ccda/StructureDefinition/CCDA-on-FHIR-History-and-Physical
Consultation Note	http://hl7.org/fhir/us/ccda/StructureDefinition/CCDA-on-FHIR-Consultation-Note
Referral Note	http://hl7.org/fhir/us/ccda/StructureDefinition/CCDA-on-FHIR-Referral-Note
Procedure Note	http://hl7.org/fhir/us/ccda/StructureDefinition/CCDA-on-FHIR-Procedure-Note
Transfer Summary	http://hl7.org/fhir/us/ccda/StructureDefinition/CCDA-on-FHIR-Transfer-Summary
Operative Note	http://hl7.org/fhir/us/ccda/StructureDefinition/CCDA-on-FHIR-Operative-Note
Care Plan	http://hl7.org/fhir/us/ccda/StructureDefinition/CCDA-on-FHIR-Care-Plan

You can import Clinical Notes of the above types and export them from your Health Gorilla account.

Read existing Clinical Notes

Use FHIR Composition READ operation to read Clinical Note.
Or you can use FHIR Composition ‘Generate a document’ operation to take the Composition and all related data in one Bundle.

Create new Clinical Note flow:

You should pack all related data into single Bundle of type ‘document’. See FHIR Documents http://hl7.org/fhir/stu3/documents.html
Then you should execute FHIR Bundle Create operation (HTTP POST)
The operation outcome contains link to the newly created Clinical Note

Subscriptions

The Subscription resource allows you to be notified about modifications of Health Gorilla resources in a most convenient way. Active Subscription will be called by Health Gorilla when corresponding resource matching the Subscription criteria has been modified. If call to a Subscription failed then we will try again in 15 minutes. We will keep trying to successfully call Subscription's endpoint with 15 minutes intervals.
Subscription will be disabled and we will not try to call it again until you reenable it if one of the following is true:

Last successful Subscription call is 3 days or older and Subscription calls failed more than 10 times
There are no successful Subscription calls and Subscription calls failed more than 20 times

You can use Subscription endpoint to create and manage subscriptions.

Subscription Limit

🚧
Subscription Limit
Health Gorilla allows 30 active subscriptions by default. This limit can be increased if needed. To request a limit increase, please contact customer support. Going over the limit will return a 422 response code and an error message.

FHIR Resource: Subscription https://www.hl7.org/fhir/subscription.html

https://api.healthgorilla.com/fhir/Subscription

FHIR Operations

The following operations are currently supported:

1. Read

HTTP Request	Method	Action
/Subscription/{ID}	GET	Get Subscription by ID

2. Search

HTTP Request	Method	Action
/Subscription?[parameter={value}]	GET

Parameters:

Key	Type	Description
status	Token	The current state of the subscription (active, requested, error, off)
type	Token	The type of channel for the sent notifications

3. Delete

HTTP Request	Method	Action
/Subscription	DELETE	Deletes subscription

4. Create

HTTP Request	Method	Action
/Subscription	POST	Creates new subscription

Limited number of resources is supported, while some resources support filters that you can use in criteria:

Resource	Additional attributes you can use in criteria	Payload
DiagnosticReport	patient category * status
DocumentReference	patient class * type
DocumentReference.OCR		application/hg-ocr+json
RequestGroup	* patient
ProcedureRequest	* patient
FaxMessage	direction deliveryFailed
DirectMessage	* direction
Patient	gender birthDate [eq, gt, lt] * postalCode
Patient.P360		application/hg-event+json
Condition	* patient
Consent	* patient
AllergyIntolerance	* patient
Immunization	* patient
MedicationRequest	* patient
MedicationStatement	* patient
MedicationDispense	* patient
NutritionOrder	* patient
Encounter	* patient
CarePlan	* patient
DeviceUseStatement	* patient
Observation	* patient, category
FamilyMemberHistory	* patient
Goal	* patient
Procedure	* patient
Coverage	* patient (required)	none

Examples

4.1. Retrieve Subscriptions by type:

https://api.healthgorilla.com/fhir/Subscription
?type=http://hl7.org/fhir/subscription-channel-type|rest-hook

4.2. Create new subscription for DiagnosticReport resource updates:

https://api.healthgorilla.com/fhir/Subscription

Headers:
Content-Type: application/json

{
  "resourceType": "Subscription",
  "status": "active",
  "end": "2021-01-01T00:00:00Z",
  "reason": "Monitor new neonatal function",
  "criteria": "DiagnosticReport",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://myservice.com/healthgorilla/webhook",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Bearer secret-token-abc-123"
    ]
  }
}

4.3. Create new subscription for failed outgoing FaxMessage resources.

This subscription will be called when Health Gorilla can not deliver electronic fax to the recipient. See FaxResource for more information.

https://api.healthgorilla.com/fhir/Subscription

Headers:
Content-Type: application/json

{
    "resourceType": "Subscription",
    "status": "active",
    "end": "2020-01-01T00:00:00Z",
    "reason": "Dev",
    "criteria": "FaxMessage?direction=OUT&deliveryFailed=true",
    "channel": {
        "type": "rest-hook",
        "endpoint": "https://myservice.com/healthgorilla/webhook",
        "payload": "application/hg-event+json",
        "header": [
            "Authorization: Bearer secret-token-hg"
        ]
    }
}

4.4. Create new subscription with the REST hook signing secret

Health Gorilla can sign payload of your Subscription calls with HMAC-SHA Signature.
Below is an example how can you specify signature's secret to be used. Note that you can not read the secret back. Endpoint returns only key id and expiration date.

{
    "resourceType": "Subscription",
    "status": "active",
    "end": "2022-01-01T00:00:00Z",
    "reason": "Testing",
    "criteria": "Patient",
    "channel": {
        "type": "rest-hook",
        "endpoint": "https://qaadmin.healthgorilla.com/extsub/webhook",
        "payload": "application/hg-ocr+json",
        "header": [
            "Authorization: Bearer accc5e72ac51fc53c6881b9a5d122765"
        ],
        "extension": [
            {
                "url": "https://www.healthgorilla.com/fhir/StructureDefinition/subscription-channelSecret",
                "extension": [
                    {
                        "url": "value",
                        "valueString": "my-signing-key"
                    },
                    {
                        "url": "id",
                        "valueString": "key-1"
                    },
                    {
                        "url": "end",
                        "valueDateTime": "2022-02-02T02:02:02+03:00"
                    }
                ]
            }
        ]
    }
}

Notification request payload headers and signature will be constructed as follows:

Header Name	Definition
Date	day-name, day month year hour:minute:second GMT
Digest	SHA-512 checksum of the payload
X-Hg-EventId	The ID of the event
X-Hg-EventCreated	When the event was issued
X-Hg-Signature	HMAC with the SHA512 hash function

In order to verify signature Subscription responder should:

Read Date, X-Hg-EventId and X-Hg-Signature headers of the request
Construct StringToSign value like:

StringToSign = <Date> + "\n" +
               <X-Hg-EventId> + "\n" +
               <Digest>

Calculate the expected signature by computing HMAC with the SHA512 hash function and then adding 'sha512=' as a prefix
Compare the signature in the request header to the calculated expected signature

5. Update

5.1 Update Subscription.channel.header

The subscription endpoint supports the FHIR Patch operation and accepts a JSON Patch payload.

Path	Operations
/channel/header	- add - replace - remove

PATCH /fhir/Subscription/1e2d645b16673dd785f371d8 HTTP/1.1 
Host: api.healthgorilla.com
Content-Type: application/json-patch+json 
{
    "op": "add",
    "path": "/channel/header",
    "value": [
        "X-WebHook-Key: my-key",
        "Authorization: Bearer accc5e72ac51fc53c6881b9a5d122765"
    ]
}

5.1 Update Signing Secret

Operation: FHIR PATCH
Format: Json PATCH
Operations: add/replace/remove

PATCH /fhir/Subscription/1e2d645b16673dd785f371d8 HTTP/1.1 
Host: api.healthgorilla.com
Content-Type: application/json-patch+json 
{
    "op": "add",
    "path": "/channel/secret",
    "value": {
        "value" : "my-key",
        "id" : "hmac-256-1",
        "end" : "2022-02-02T02:02:02"
    }
}

Subscription channel types

Health Gorilla supports rest-hook and web socket channels from the list https://www.hl7.org/fhir/valueset-subscription-channel-type.html

Rest hook

You can receive callback to the specified endpoint. And this is a highly recommended to add HTTP headers to the channel, that you will use to authorize the callback.
Only endpoints that use TLS1.2+ can be accepted.

Supported payloads:

Payload	Description
No payload	See https://www.hl7.org/fhir/subscription.html#2.46.6.1 for details
application/fhir+xml	See https://www.hl7.org/fhir/subscription.html#2.46.6.1 for details
application/fhir+json	See https://www.hl7.org/fhir/subscription.html#2.46.6.1 for details
application/hg-event+json	Health Gorilla sends simple JSON event to client's endpoint with the resource type and resource’s identifier that triggered the event. For example: { “resource” : "RequestGroup", “id” : "RequestGroup/d6fjlvj9gjb9djlaww8q" }
application/hg-ocr+json	{ "resource":"DocumentReference", "id":"7e00155db23e480d67609b59", "ocr":[ { "name":"laboratory_result.pdf", "contentType":"application/pdf", "success":true, "entities":[ { "resource":"Entity", "id":0, "category":"PROTECTED_HEALTH_INFORMATION", "type":"DATE", "text":"Mon 05 Nov 2012", "score":0.99408334 }, { "resource":"Entity", "id":52, "category":"MEDICAL_CONDITION", "type":"DX_NAME", "text":"venous thrombosis", "score":0.9674222, "traits":[ { "resource":"Trait", "name":"DIAGNOSIS", "score":0.9529462 } ] }, ... ] } ] }

If you use no-payload mode, then you can query Health Gorilla FHIR server for the list of recently modified resources by appending “&_lastUpdated=” parameter to the search criteria.

Web Socket

You can connect to secure Web Socket and receive runtime notifications.

To do so you need to use OAuth access token to authorize connection.

Web Socket endpoint is defined in the server's CapabilityStatement.
See https://www.hl7.org/fhir/extension-capabilitystatement-websocket.html for more information

Example

Subscribe for new MedicationRequest received for the given patient.

{
  "resourceType": "Subscription",
  "status": "active",
  "end": "2022-01-01T00:00:00Z",
  "reason": "Monitor activity",
  "criteria": "MedicationRequest?patient=03db4352ee0190ad5e9e6748",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://myservice.com/healthgorilla/webhook",
    "payload": "application/hg-event+json",
    "header": [
      "Authorization: Bearer my-secret-token"
    ]
  }
}

ADT Message Subscription

ADT messages contain important updates to patient demographic information and their clinical "status", e.g. admissions, discharges, and transfers, which can be important for patient care management.

You can be notified when new ADT Message is received in your account.

Create a new subscription:

Property	Value
Subscription.channel.type	messaging
Subscription.channel.endpoint	Include operation $process-message
Subscription.channel.payload	application/fhir+json

{
    "resourceType": "Subscription",
    "status": "active",
    "end": "2022-01-01T00:00:00Z",
    "reason": "ADT events",
    "criteria": "Bundle?message.event=admin-notify",
    "channel": {
        "type": "message",
        "endpoint": "https:/fhir.mycompany.com/extsub/webhook/$process-message",
        "payload": "application/fhir+json"
    }
}

Read ADT events

Read ADT events created since the specified date:

Parameter	Type	Details	Required
message.event	token	admin-notify	Yes
message.focus	reference	patient logical ID	No
_lastUpdated	date		No
_offset	number	Default: 0	No
_count	number	Default: 100	No
eventType	string	One of codes A01 - A62	No

{{portalUrl}}/fhir/Bundle?message.event=admin-notify&_lastUpdated=2021

Example: read ADT event by ID

{{portalUrl}}/fhir/Bundle?message._id=234b056061f93146a983072f

{
    "resourceType": "Bundle",
    "id": "0ef188e4-e0ab-4006-b354-6bd78f62eda4",
    "meta": {
        "lastUpdated": "2021-07-09T20:52:15.434+00:00"
    },
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "https://api.healthgorilla.com/fhir/Bundle?message._id=234b056061f93146a983072f"
        }
    ],
    "entry": [
        {
            "fullUrl": "https://api.healthgorilla.com/fhir/Bundle/91fdeae7-12ac-4c0f-8886-fa1d9e8de2e0",
            "resource": {
                "resourceType": "Bundle",
                "id": "91fdeae7-12ac-4c0f-8886-fa1d9e8de2e0",
                "type": "message",
                "entry": [
                    {
                        "fullUrl": "urn:uuid:234b056061f93146a983072f",
                        "resource": {
                            "resourceType": "MessageHeader",
                            "id": "09c71b60ec62c22dc09267ac",
                            "contained": [
                                {
                                    "resourceType": "Organization",
                                    "id": "1",
                                    "name": "GOOD HEALTH HOSPITAL"
                                }
                            ],
                            "event": {
                                "system": "http://hl7.org/fhir/message-events",
                                "code": "admin-notify",
                                "display": "admin-notify"
                            },
                            "sender": {
                                "reference": "#1"
                            },
                            "timestamp": "1988-08-18T11:26:00+00:00",
                            "source": {
                                "name": "ADT1",
                                "software": "ADT1"
                            },
                            "focus": [
                                {
                                    "reference": "Patient/09c71b60b4b8d62360f1b8f6",
                                    "display": "ADAM A EVERYMAN"
                                }
                            ]
                        }
                    },
                    {
                        "fullUrl": "urn:uuid:patient",
                        "resource": {
                            "resourceType": "Patient",
                            "id": "patient",
                            "meta": {
                                "versionId": "1612433161124",
                                "lastUpdated": "2021-02-04T10:06:01.124+00:00",
                                "profile": [
                                    "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
                                    "http://fhir.org/guides/argonaut/StructureDefinition/argo-patient"
                                ]
                            },
                            "text": {
                                "status": "generated",
                                "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">ADAM A EVERYMAN, 60y.o., Male, GREENSBORO, NC, United States</div>"
                            },
                            "identifier": [
                                {
                                    "use": "usual",
                                    "type": {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/v2/0203",
                                                "code": "MR",
                                                "display": "Medical record number"
                                            }
                                        ],
                                        "text": "Medical record number"
                                    },
                                    "system": "https://www.healthgorilla.com",
                                    "value": "09c71b60b4b8d62360f1b8f6"
                                },
                                {
                                    "type": {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/identifier-type",
                                                "code": "SB",
                                                "display": "Social Beneficiary Identifier"
                                            }
                                        ],
                                        "text": "Social Beneficiary Identifier"
                                    },
                                    "system": "http://hl7.org/fhir/sid/us-ssn",
                                    "value": "444333333"
                                },
                                {
                                    "type": {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/v2/0203",
                                                "code": "MR",
                                                "display": "Medical record number"
                                            }
                                        ],
                                        "text": "Medical record number"
                                    },
                                    "value": "391141"
                                }
                            ],
                            "active": true,
                            "name": [
                                {
                                    "text": "ADAM A EVERYMAN",
                                    "family": "EVERYMAN",
                                    "given": [
                                        "ADAM",
                                        "A"
                                    ]
                                }
                            ],
                            "telecom": [
                                {
                                    "system": "phone",
                                    "value": "(555) 555-2004",
                                    "use": "home"
                                },
                                {
                                    "system": "phone",
                                    "value": "(555) 555-2004",
                                    "use": "work"
                                }
                            ],
                            "gender": "male",
                            "birthDate": "1961-06-15",
                            "address": [
                                {
                                    "text": "2222 HOME STREET, GREENSBORO, NC 27401",
                                    "line": [
                                        "2222 HOME STREET"
                                    ],
                                    "city": "GREENSBORO",
                                    "state": "NC",
                                    "postalCode": "27401-1020",
                                    "country": "USA"
                                }
                            ],
                            "maritalStatus": {
                                "coding": [
                                    {
                                        "system": "http://hl7.org/fhir/v3/MaritalStatus",
                                        "code": "U",
                                        "display": "Unmarried"
                                    }
                                ],
                                "text": "Single"
                            },
                            "link": [
                                {
                                    "other": {
                                        "reference": "Patient/09c71b60b4b8d62360f1b8f6",
                                        "display": "ADAM A EVERYMAN"
                                    },
                                    "type": "refer"
                                }
                            ]
                        }
                    },
                    {
                        "fullUrl": "urn:uuid:enc",
                        "resource": {
                            "resourceType": "Encounter",
                            "id": "enc",
                            "contained": [
                                {
                                    "resourceType": "Practitioner",
                                    "id": "1",
                                    "identifier": [
                                        {
                                            "value": "004777"
                                        }
                                    ],
                                    "name": [
                                        {
                                            "text": "AARON A ATTEND",
                                            "family": "ATTEND",
                                            "given": [
                                                "AARON",
                                                "A"
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "resourceType": "Location",
                                    "id": "2",
                                    "name": "01",
                                    "physicalType": {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/location-physical-type",
                                                "code": "bd",
                                                "display": "Bed"
                                            }
                                        ],
                                        "text": "Bed"
                                    },
                                    "partOf": {
                                        "reference": "#3"
                                    }
                                },
                                {
                                    "resourceType": "Location",
                                    "id": "3",
                                    "name": "2012",
                                    "physicalType": {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/location-physical-type",
                                                "code": "ro",
                                                "display": "Room"
                                            }
                                        ],
                                        "text": "Room"
                                    },
                                    "partOf": {
                                        "reference": "#4"
                                    }
                                },
                                {
                                    "resourceType": "Location",
                                    "id": "4",
                                    "name": "2000"
                                }
                            ],
                            "class": {
                                "system": "http://terminology.hl7.org/CodeSystem/v2-0004",
                                "code": "I",
                                "display": "Inpatient"
                            },
                            "subject": {
                                "reference": "Patient/patient"
                            },
                            "participant": [
                                {
                                    "type": [
                                        {
                                            "coding": [
                                                {
                                                    "system": "http://hl7.org/fhir/v3/ParticipationType",
                                                    "code": "ATND",
                                                    "display": "Attender"
                                                }
                                            ]
                                        }
                                    ],
                                    "individual": {
                                        "reference": "#1"
                                    }
                                }
                            ],
                            "location": [
                                {
                                    "location": {
                                        "reference": "#2"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

Patient360 Subscription

You can be notified when a batch of CDA documents is imported from the data exchange networks. Patient360 Subscription will be triggered in the following scenarios:

Documents for the patient are queried and retrieved via Patient360 UI
Single document is imported for the patient
Batch of documents is imported for the patient

Create a new subscription:

Property	Value
Subscription.criteria	Patient.P360
Subscription.channel.payload	application/hg-event+json

{
    "resourceType": "Subscription",
    "status": "active",
    "end": "2022-01-01T00:00:00Z",
    "reason": "Patient360",
    "criteria": "Patient.P360",
    "channel": {
        "type": "rest-hook",
        "endpoint": "https://mysyte.com/healthgorilla/callback",
        "payload": "application/hg-event+json",
        "header": [
            "X-Hg-Callback-Key: accc5e72ac51fc53c6881b9a5d122765=="
        ]
    }
}

If CDA documents have been imported, HealthGorilla makes a webhook call and provides the reference to the patient.

POST /healthgorilla/callback HTTP/1.1 
Host: mysyte.com/healthgorilla 
X-Hg-Callback-Key: accc5e72ac51fc53c6881b9a5d122765==
Content-Type: application/json 
{
    “resource” : "Patient",
    “id” : "Patient/e9b7c05fb9c6de7fb3abb4b1" 
}

Error Handling

The API will always return sensible HTTP status code.

API errors are of 2 types:

400 series status codes for client issues
500 series status codes for server issues.

Common HTTP Status codes returned on errors:

400 Bad Request - search could not be processed or failed basic FHIR validation rules
401 Not Authorized - authorization is required for the interaction that was attempted
404 Not Found - resource type not supported, or not a FHIR end-point
422 Unprocessable Entity - resource was rejected by the server because it "violated applicable FHIR profiles or server business rules"
500 - Internal Server Error

Along with the Status Code the API will return an OperationOutcome resource as response containing details about the error. Here is an example of OperationOutcome object:

{
   "resourceType": "OperationOutcome",
   "issue": [
       {
"severity": "error",
           "code": "processing",
           "diagnostics": "Invalid request: The FHIR endpoint on this server does not know how to handle GET operation[Patient] with parameters [[wrong_parameter]]"
       }
   ]
}

Appendix A

Resource samples

DiagnosticReport

{
    "resourceType": "DiagnosticReport",
    "id": "f816835975440b570eed9683",
    "meta": {
        "lastUpdated": "2017-08-03T12:30:34.527+00:00"
    },
    "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Emr Test Compass Lab Services Result 08/03/2017 12:30 PM</div>"
    },
    "contained": [
        {
            "resourceType": "ProcedureRequest",
            "id": "1",
            "status": "unknown",
            "intent": "order",
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "103693007",
                            "display": "Diagnostic procedure"
                        }
                    ]
                }
            ],
            "subject": {
                "reference": "Patient/6a1783599edf3ae52e51947a",
                "display": "Emr Test"
            },
            "requester": {
                "agent": {
                    "reference": "Practitioner/c50f6150e4b8c94c4ba3b23d",
                    "display": "John Gorilla Doe, Ph. D. Psychology"
                }
            }
        }
    ],
    "identifier": [
        {
            "system": "https://www.healthgorilla.com",
            "value": "f816835975440b570eed9683"
        },
        {
            "type": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                        "code": "ACSN",
                        "display": "Accession ID"
                    }
                ],
                "text": "Accession Number"
            },
            "value": "770165"
        }
    ],
    "basedOn": [
        {
            "reference": "#1"
        }
    ],
    "status": "final",
    "category": {
        "coding": [
            {
                "system": "http://hl7.org/fhir/v2/0074",
                "code": "LAB",
                "display": "Laboratory"
            }
        ],
        "text": "Laboratory"
    },
    "code": {
        "text": "CMOR, PDF Report"
    },
    "subject": {
        "reference": "Patient/6a1783599edf3ae52e51947a",
        "display": "Emr Test"
    },
    "issued": "2017-08-02T17:49:10.000+00:00",
    "performer": [
        {
            "actor": {
                "reference": "Organization/f-f6c78159fc6d1019e302215f",
                "display": "Compass Lab Services"
            }
        }
    ],
    "result": [
        {
            "reference": "Observation/f816835975440b570eed9683-2000",
            "display": "PDF Report"
        },
        {
            "reference": "Observation/f816835975440b570eed9683-1304040",
            "display": "CMOR"
        }
    ],
    "extension": [
        {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/diagnosticreport-fasting",
            "valueBoolean": true
        }
    ]
}

Observation (Observation Group)

{
    "resourceType": "Observation",
    "id": "f816835975440b570eed9683-1304040",
    "meta": {
        "lastUpdated": "2017-08-03T12:30:34.527+00:00"
    },
    "extension": [
        {
            "url": "http://hl7.org/fhir/StructureDefinition/event-partOf",
            "valueReference": {
                "reference": "DiagnosticReport/f816835975440b570eed9683",
                "display": "CMOR, PDF Report"
            }
        }
    ],
    "status": "unknown",
    "category": [
        {
            "coding": [
                {
                    "system": "http://hl7.org/fhir/observation-category",
                    "code": "laboratory",
                    "display": "Laboratory"
                }
            ]
        }
    ],
    "code": {
        "text": "CMOR"
    },
    "subject": {
        "display": "Emr Test"
    },
    "effectiveDateTime": "2017-08-01T19:00:00+00:00",
    "issued": "2017-08-02T17:49:10.000+00:00",
    "performer": [
        {
            "reference": "Organization/f-f6c78159fc6d1019e302215f",
            "display": "Compass Lab Services"
        }
    ],
    "related": [
        {
            "type": "has-member",
            "target": {
                "reference": "Observation/f816835975440b570eed9683-1304040-1",
                "display": "Hydromorphone"
            }
        },
        {
            "type": "has-member",
            "target": {
                "reference": "Observation/f816835975440b570eed9683-1304040-2",
                "display": "Hydromorphone, Quan"
            }
        },
        {
            "type": "has-member",
            "target": {
                "reference": "Observation/f816835975440b570eed9683-1304040-3",
                "display": "Morphine"
            }
        },
        {
            "type": "has-member",
            "target": {
                "reference": "Observation/f816835975440b570eed9683-1304040-4",
                "display": "Morphine, Quan"
            }
        }
    ]
}

Observation (Observation Result)

{
    "resourceType": "Observation",
    "id": "f816835975440b570eed9683-1304040-1",
    "meta": {
        "lastUpdated": "2017-08-03T12:30:34.527+00:00"
    },
    "extension": [
        {
            "url": "http://hl7.org/fhir/StructureDefinition/event-partOf",
            "valueReference": {
                "reference": "Observation/f816835975440b570eed9683-1304040"
            }
        }
    ],
    "status": "final",
    "category": [
        {
            "coding": [
                {
                    "system": "http://hl7.org/fhir/observation-category",
                    "code": "laboratory",
                    "display": "Laboratory"
                }
            ]
        }
    ],
    "code": {
        "text": "Hydromorphone"
    },
    "subject": {
        "display": "Emr Test"
    },
    "effectiveDateTime": "2017-08-02T16:21:35+00:00",
    "issued": "2017-08-02T17:49:10.000+00:00",
    "valueString": "Negative",
    "interpretation": {
        "coding": [
            {
                "system": "http://hl7.org/fhir/v2/0078",
                "code": "N",
                "display": "Normal"
            }
        ]
    },
    "referenceRange": [
        {
            "text": "Cutoff level 50"
        }
    ]
}

Telephonic Encounter

Terminology

Encounter Type

System	Code	Display
https://www.healthgorilla.com/fhir/encounter-type	telephonic-encounter	Telephonic Encounter

Participant Type

System	Code	Display	Description
http://hl7.org/fhir/v3/ParticipationType	PPRF	Primary performer	Author
https://www.healthgorilla.com/fhir/participation-type	assignee	Assignee
https://www.healthgorilla.com/fhir/participation-type	cc	CC User

Encounter Processing Status

System: https://www.healthgorilla.com/fhir/encounter-processing-status

Code	Display
assigned	Assigned
completed	Completed

Reason code

System: https://www.healthgorilla.com/encounter-reason

Code	Display
billing	Billing
refill-rx	Refill/Rx
needs-callBack	Needs call back
records-request	Records request
insurance-updated	Insurance info updated
copay	Copay
results	Results
second-call	Second call
returned-call	Returned call
school-work-excuse	School/work excuse
urgent-visit-request	Urgent visit request
phone-consult	Phone consult

Profile and Extensions

Telephonic Encounter Profile

https://healthgorilla.com/fhir/StructureDefinition/hg-telephonic-encounter

Processing Status Extension

https://www.healthgorilla.com/fhir/StructureDefinition/encounter-processingStatus

{
  "url": "https://www.healthgorilla.com/fhir/StructureDefinition/encounter-processingStatus",
  "valueCoding": {
    "system": "https://www.healthgorilla.com/fhir/encounter-processing-status",
    "code": "completed",
    "display": "Completed"
  }
}

Note Extension

https://www.healthgorilla.com/fhir/StructureDefinition/encounter-note

{
  "url": "https://www.healthgorilla.com/fhir/StructureDefinition/encounter-note",
  "valueString": "Your note here"
}

Action Taken

https://www.healthgorilla.com/fhir/StructureDefinition/encounter-actionTaken

Parameter	Type	Details
date	datetime	The timestamp
performer	reference	Reference to the practitioner.
note	string	Text

An action that has already been taken

{
  "url": "https://www.healthgorilla.com/fhir/StructureDefinition/encounter-actionTaken",
  "extension": [
    {
      "url": "date",
      "valueDateTime": "2020-10-12T17:08:14+03:00"
    },
    {
      "url": "performer",
      "valueReference": {
        "reference": "Practitioner/ceda4352e8f6405dd2e42f09",
        "display": "John Doe, M.D., Sacred Health Hospital"
      }
    },
    {
      "url": "note",
      "valueString": "Reassigned this telephonic encounter to Elliot Reid, John Doe"
    }
  ]
}

A new action to apply (create/update)

parameter	Details
date	skipped
performer	Optional
note	Required

{
  "url": "https://www.healthgorilla.com/fhir/StructureDefinition/encounter-actionTaken",
  "extension": [
    {
      "url": "performer",
      "valueReference": {
        "reference": "Practitioner/ceda4352e8f6405dd2e42f09",
        "display": "John Doe, M.D., Sacred Health Hospital"
      }
    },
    {
      "url": "note",
      "valueString": "Reassigned this telephonic encounter to Elliot Reid, John Doe"
    }
  ]
}

Create new telephonic encounter

https://api.healthgorilla.com/fhir/Encounter

{
  "resourceType": "Encounter",
  "meta": {
    "profile": ["https://healthgorilla.com/fhir/StructureDefinition/hg-telephonic-encounter"]
  },
  "extension": [
    {
      "url": "https://www.healthgorilla.com/fhir/StructureDefinition/encounter-note",
      "valueString": "Created for testing purposes."
    },
    {
      "url": "https://www.healthgorilla.com/fhir/StructureDefinition/encounter-processingStatus",
      "valueCoding": {
        "system": "https://www.healthgorilla.com/fhir/encounter-processing-status",
        "code": "assigned",
        "display": "Assigned"
      }
    },
    {
      "url": "https://www.healthgorilla.com/fhir/StructureDefinition/encounter-actionTaken",
      "extension": [
        {
          "url": "performer",
          "valueReference": {
            "reference": "Practitioner/ceda4352e8f6405dd2e42f09",
            "display": "John Doe (Sacred Health Hospital)"
          }
        },
        {
          "url": "note",
          "valueString": "Assigned this telephonic encounter to Elliot Reid"
        }
      ]
    }
  ],
  "status": "finished",
  "class": {
    "system": "http://hl7.org/fhir/v3/ActCode",
    "code": "VR",
    "display": "virtual"
  },
  "type": [
    {
      "coding": [
        {
          "system": "https://www.healthgorilla.com/fhir/encounter-type",
          "code": "telephonic-encounter",
          "display": "Telephonic Encounter"
        }
      ],
      "text": "Telephonic Encounter"
    }
  ],
  "subject": {
    "reference": "Patient/03db43522cc01432572e0a53",
    "display": "Bart Simpson"
  },
  "participant": [
    {
      "type": [
        {
          "coding": [
            {
              "system": "http://hl7.org/fhir/v3/ParticipationType",
              "code": "PPRF",
              "display": "primary performer"
            }
          ],
          "text": "primary performer"
        }
      ],
      "individual": {
        "reference": "Practitioner/ceda4352e8f6405dd2e42f09",
        "display": "John Doe"
      }
    },
    {
      "type": [
        {
          "coding": [
            {
              "system": "https://www.healthgorilla.com/fhir/participation-type",
              "code": "assignee",
              "display": "Assignee"
            }
          ],
          "text": "Assignee"
        }
      ],
      "individual": {
        "reference": "Practitioner/5e093356c06e5fec973c8e76",
        "display": "Elliot Reid"
      }
    },
    {
      "type": [
        {
          "coding": [
            {
              "system": "https://www.healthgorilla.com/fhir/participation-type",
              "code": "cc",
              "display": "Carbon Copy"
            }
          ],
          "text": "Carbon Copy"
        }
      ],
      "individual": {
        "reference": "Practitioner/fc076a524383b188ffc10051",
        "display": "Robert Kelso"
      }
    }
  ],
  "reason": [
    {
      "text": "Test"
    }
  ]
}

Parameters:
Status: Assigned
Author: John Doe
Assignee: Elliot Reid
CC: Robert Kelso
Reason: Other(Test)
Note: Created for testing purposes.
Action Taken: Assigned this telephonic encounter to Elliot Reid

Update

You can modify:

processing status (assigned -> completed)
note
assignee
cc user

You can add:

action taken

https://api.healthgorilla.com/fhir/Encounter/ENCOUNTER_ID

{
  "resourceType": "Encounter",
  "id": "te-777eeb5860a3973dda5b0a86",
  "meta": {
    "profile": ["https://healthgorilla.com/fhir/StructureDefinition/hg-telephonic-encounter"]
  },
  "extension": [
    {
      "url": "https://www.healthgorilla.com/fhir/StructureDefinition/encounter-note",
      "valueString": "Created for testing purposes and then modified."
    },
    {
      "url": "https://www.healthgorilla.com/fhir/StructureDefinition/encounter-processingStatus",
      "valueCoding": {
        "system": "https://www.healthgorilla.com/fhir/encounter-processing-status",
        "code": "completed",
        "display": "Completed"
      }
    },
    {
      "url": "https://www.healthgorilla.com/fhir/StructureDefinition/encounter-actionTaken",
      "extension": [
        {
          "url": "performer",
          "valueReference": {
            "reference": "Practitioner/5e093356c06e5fec973c8e76",
            "display": "Elliot Reid"
          }
        },
        {
          "url": "note",
          "valueString": "Reassigned this telephonic encounter to John Doe"
        }
      ]
    }
  ],
  "identifier": [
    {
      "system": "https://www.healthgorilla.com",
      "value": "777eeb5860a3973dda5b0a86"
    }
  ],
  "status": "finished",
  "class": {
    "system": "http://hl7.org/fhir/v3/ActCode",
    "code": "VR",
    "display": "virtual"
  },
  "type": [
    {
      "coding": [
        {
          "system": "https://www.healthgorilla.com/fhir/encounter-type",
          "code": "telephonic-encounter",
          "display": "Telephonic Encounter"
        }
      ],
      "text": "Telephonic Encounter"
    }
  ],
  "subject": {
    "reference": "Patient/03db43522cc01432572e0a53",
    "display": "Bart Simpson"
  },
  "participant": [
    {
      "type": [
        {
          "coding": [
            {
              "system": "http://hl7.org/fhir/v3/ParticipationType",
              "code": "PPRF",
              "display": "primary performer"
            }
          ],
          "text": "primary performer"
        }
      ],
      "individual": {
        "reference": "Practitioner/ceda4352e8f6405dd2e42f09",
        "display": "John Doe"
      }
    },
    {
      "type": [
        {
          "coding": [
            {
              "system": "https://www.healthgorilla.com/fhir/participation-type",
              "code": "assignee",
              "display": "Assignee"
            }
          ],
          "text": "Assignee"
        }
      ],
      "individual": {
        "reference": "Practitioner/5e093356c06e5fec973c8e76",
        "display": "Elliot Reid"
      }
    },
    {
      "type": [
        {
          "coding": [
            {
              "system": "https://www.healthgorilla.com/fhir/participation-type",
              "code": "assignee",
              "display": "Assignee"
            }
          ],
          "text": "Assignee"
        }
      ],
      "individual": {
        "reference": "Practitioner/ceda4352e8f6405dd2e42f09",
        "display": "John Doe"
      }
    },
    {
      "type": [
        {
          "coding": [
            {
              "system": "https://www.healthgorilla.com/fhir/participation-type",
              "code": "cc",
              "display": "Carbon Copy"
            }
          ],
          "text": "Carbon Copy"
        }
      ],
      "individual": {
        "reference": "Practitioner/fc076a524383b188ffc10051",
        "display": "Robert Kelso"
      }
    }
  ],
  "period": {
    "start": "2017-04-10T15:45:11+03:00"
  },
  "reason": [
    {
      "text": "Test"
    }
  ]
}

Parameters:
Status: Completed
Author: John Doe
Assignee: Elliot Reid, John Doe
CC: Robert Kelso
Reason: Other(Test)
Note: Created for testing purposes and then modified.
Action Taken: Assigned this telephonic encounter to Elliot Reid
Action Taken: Reassigned this telephonic encounter to John Doe

Search by patient

Parameter	Type	Description
patient	reference	Reference to the patient
type	token	https://www.healthgorilla.com/fhir/encounter-type%7Ctelephonic-encounter
processing-status	token	Any code from https://www.healthgorilla.com/fhir/encounter-processing-status
_lastUpdated	datetime

Return all telephonic encounters for the patient with instance (logical) id 'd5da4352b3f978a445475a22'

https://api.healthgorilla.com/fhir/Encounter?patient=d5da4352b3f978a445475a22
&type=https://www.healthgorilla.com/fhir/encounter-type%7Ctelephonic-encounter
&_format=json

Lookup for assigned telephonic encpounters for the patient with global id 'd5da4352b3f978a445475a22'

https://api.healthgorilla.com/fhir/Encounter?patient.identifier=https://www.healthgorilla.com%7Cd5da4352b3f978a445475a22
&processing-status=assigned
&type=https://www.healthgorilla.com/fhir/encounter-type%7Ctelephonic-encounter
&_format=json

Search by last modified

Parameter	Type	Description
type	token	https://www.healthgorilla.com/fhir/encounter-type%7Ctelephonic-encounter
processing-status	token	Any code from https://www.healthgorilla.com/fhir/encounter-processing-status
_lastUpdated	datetime
_offset	number
_count	number

Return all telephonic encounters updated since year 2019.

https://api.healthgorilla.com/fhir/Encounter?
type=https://www.healthgorilla.com/fhir/encounter-type%7Ctelephonic-encounter
&_lastUpdated=gt2019
&_format=json

Delete (archive)

https://api.healthgorilla.com/fhir/Encounter/ENCOUNTER_ID

6. PDF

https://api.healthgorilla.com/fhir/Encounter/ENCOUNTER_ID/$pdf

Example

https://api.healthgorilla.com/fhir/Encounter/te-2b56845fc3cfc79409dec5b8/$pdf

<Parameters xmlns="http://hl7.org/fhir">
    <parameter>
        <name value="url"/>
        <valueString value="https://api.healthgorilla.com/fhir/Binary/tmp-2d5a855f4f78fc184e3d9ab8"/>
    </parameter>
    <parameter>
        <name value="contentType"/>
        <valueString value="application/pdf"/>
    </parameter>
    <parameter>
        <name value="size"/>
        <valuePositiveInt value="2427"/>
    </parameter>
    <parameter>
        <name value="checksum"/>
        <valueString value="f4a25fc5110d8f70b7b56838de338dcc"/>
    </parameter>
    <parameter>
        <name value="expiredAt"/>
        <valueDateTime value="2020-10-13T11:11:33+03:00"/>
    </parameter>
</Parameters>

Overview

Observation

FHIR Operations

1. Read

2. Search

2.1. Retrieve Laboratory Observations by patient

2.2. Retrieve Vital Signs by patient

2.3. Retrieve Social History by patient

2.4. Retrieve Functional Status by patient

2.5. Search records updated saince March 2019

2.6. Retrieve records for the given patient updated in 2018

3. Create

3.1. Add Vital Sign

3.2. Add Social History

3.3. Add Laboratory Observation

4. Update

5. Delete

Procedure

FHIR Operations

1. Read

2. Search

2.1. Retrieve procedures by patient

2.2. Search records updated since March 2019

2.3. Retrieve records for the given patient updated in 2018

3. Create

4. Update

5. Delete

ProcedureRequest

FHIR Operations

1. Read

2. Search

2.1. Retrieve ProcedureRequest resources by patient and date

2.2. Retrieve ProcedureRequest resources by order ID

ReferralRequest

FHIR Operations

1.Read

2.Search

2.1. Get referral with Health Gorilla identifier '0cb02b5bb9e7f9318af8dd67', include recipient and supported documents.

2.2. Retrieve Referrals by patient updated in March 2020

3. Download PDF

4. Create

RequestGroup

FHIR Operations

1. Read

2. Search

2.1. Retrieve Order by ID

2.2. Retrieve Order by requisition ID

2.3. Retrieve Orders by Lab Reference ID

2.4. Retrieve Orders by patient and date

3. Create

4. Download PDF

Instant Message

FHIR Operations

1. Read

2. Search

2.1 Retrieve all incoming messages received starting from 09/05/2019

2.2 Retrieve InstantMessage resource with identifier of 35f3d35d12aa8d93dd9953c0

Electronic Fax

FHIR Operations

1. Read

2. Search

2.1 Retrieve all incoming fax messages received starting 09/05/2019

2.2 Retrieve FaxMessage resource with identifier of 35f3d35d12aa8d93dd9953c0

3. Send

Record Locator Service

Clinical Notes

Read existing Clinical Notes

Create new Clinical Note flow:

Subscriptions

Subscription Limit

🚧Subscription Limit

FHIR Operations

1. Read

2. Search

3. Delete

4. Create

4.1. Retrieve Subscriptions by type:

4.2. Create new subscription for DiagnosticReport resource updates:

4.3. Create new subscription for failed outgoing FaxMessage resources.

4.4. Create new subscription with the REST hook signing secret

🚧
Subscription Limit