FHIR RESTful API (Part 2)

Welcome to Health Gorilla's Developer Portal. Access API documentation for our suite of clinical data APIs.

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:

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

related

Observation (code, value)

The following attributes are required for Social History:

Name

Details

subject

code

value

The following attributes are required for Functional Status:

Name

Details

subject

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

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, gte, 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:

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 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

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:

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.

Attention! Newly created Subscription has ‘Requested’ status and need to be manually approved by Health Gorilla staff to become active.

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

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": "requested",
  "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": "requested",
    "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": "requested",
    "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": "requested",
  "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": "requested",
    "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

N

{{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:

Create a new subscription:

Property

Value

Subscription.criteria

Patient.P360

Subscription.channel.payload

application/hg-event+json

{
    "resourceType": "Subscription",
    "status": "requested",
    "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

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>