Overview

Chart Bridge enables developers to retrieve medical records for insurance purposes from data networks. This guide provides detailed instructions on how to use our API to search for an Individual’s records and retrieve clinical records from the Chart Bridge data source. Please note that patient, individual, and insured are used interchangeably in this document.

The Chart Bridge API is part of Health Gorilla's RESTful API suite and is based on HL7 FHIR STU3 and R4.

##References

HL7 FHIR

Health Gorilla RESTful API is based on FHIR protocol version 3 and 4. Some custom resource profiles are defined and extension mechanisms are used to introduce new attributes and operations that are absent in the original protocol.

Access Control

Health Gorilla implements SMART-on-FHIR profile and uses OAuth 2.0 framework for authentication and authorization. You need to obtain an access token and include it into the request to access the desired API endpoint.

user/*.*

High Level Workflow

1241 — Chart Bridge flow diagram for querying records.

Get Patient ID

To query records in the Chart Bridge network, the patient record must first exist in Health Gorilla. You can either get a patient ID using the patient search call or generate a patient ID by creating the patient.

Patient FHIR Operations

The following operations are currently supported:

1. Search

HTTP Request	Method	Action
/Patient?[parameter={value}]	GET	Retrieve the Individual Patient resources meeting the specified search criteria.

Search Parameters:

Name	Type	Description
identifier	Token	Individual's Identifier (MRN)
family	String	Individual's Family Name
given	String	Individual's Given Name
birthdate	String	Individual's DOB (in YYYY-MM-DD format)
gender	Token	Individual's Gender (male/female)
address-postalcode	String	Individual's Postal (zip) code
_lastUpdated	Date
_offset	Number
_count	Number

Search Examples

1.1 Search patients updated since March 2019

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

1.2 Search patient by MRN

https://api.healthgorilla.com/fhir/R4/Patient?identifier=https://www.healthgorilla.com|8063965523692105bfc35def

1.3 Search by patient SSN

https://api.healthgorilla.com/fhir/R4/Patient?identifier=http://hl7.org/fhir/sid/us-ssn|000-00-0001

1.4 Search by patient name

https://api.healthgorilla.com/fhir/R4/Patient?given=Homer&family=Simpson

1.5 Search all male patients who were born after October 1998 and whose given name contains 'Alex'

https://api.healthgorilla.com/fhir/R4/Patient?given:contains=Alex&birthdate=gt1998-10&gender=male

1.6 Search patients with the exact string 'Smith Johnson'. Exact searching is case sensitive

https://api.healthgorilla.com/fhir/R4/Patient?given:exact=Smith Johnson

2. Create if Patient Does Not Exist

HTTP Request	Method	Action
/Patient	POST	Creates patient resource for the individual.

The following attributes are required:

Name	Description
given	Individual's given name
family	Individual's family name
birthdate	Individual's DOB (in YYYY-MM-DD format)
gender	Individual's Gender (male/female)
address	Postal code OR city/state required but full address is recommended. *Including multiple addresses may increase the number of documents retrieved.

The following attributes are recommended:

Name	Description
phone number	telecom in FHIR Patient Resource
email	telecom in FHIR Patient Resource

2.1Patient FHIR Resource Example

{
  "resourceType": "Patient",
  "name": [
    {
      "use": "usual",
      "family": "Joe", 
      "given": [
        "Gorilla"
      ]
    }
  ],
  "address": [
    {
      "use": "home",
      "text": "123 Fake Street,  CA 90402",
      "line": [
        "123 Fake Street"
      ],
      "city": "Monica",
      "state": "CA",
      "postalCode": "90402"
    }
  ],
  "gender": "male",
  "birthDate": "1990-06-08",
  "telecom": [
    {
      "use": "home"
    },
    {
      "system": "phone",
      "value": "(111) 111 1111",
      "use": "work",
      "rank": 2
    },
    {
      "system": "phone",
      "value": "(111) 111 1111",
      "use": "mobile",
      "rank": 1
    },
    {
      "system": "email",
      "value": "[email protected]",
      "use": "work"
    }
  ]
}

2.2 Conditional Create

This method also supports conditional create. To use it, you will need to set an additional header in the POST request.
If-None-Exist:[search parameters]

Supported Parameters:

given
family
gender
birthdate

Conditional Create Header Example

If-None-Exist: given=Joe&family=Gorilla&gender=male&birthdate=1981-01-30

3. Retrieve Patient Resource when Patient Exists: Read

HTTP Request	Method	Action
/Patient/{ID}	GET	Retrieve the Individual by the FHIR Resource ID

4. Update Patient Resource

Providing more demographic information can dramatically increase the number of documents returned. This method can be used to update an existing patient resource.

HTTP Request	Method	Action
/Patient/{ID}	PUT	Updates the Patient Resource.

Get Authorization ID

A consent or authorization form is a record of a healthcare consumer's policy choices, which permits or denies identified recipient(s) or recipient role(s) to perform one or more actions within a given policy context, for specific purposes and periods of time.

To query records in the Chart Bridge network, the patient authorization/consent forms must first exist in Health Gorilla.

FHIR Resource: Consent https://hl7.org/fhir/R4/consent.html

The following attributes are supported:

Name	Description
identifier	FHIR ID of the Consent Resource
category	Classification of Consent Statement
patient	Who the consent applies to
period	Timeframe for this rule
dateTime	When the consent was created or indexed
actor	Author, Verifier or Custodian
sourceAttachment	Consent Documentation

Consent FHIR Operations

The following FHIR operations are currently supported:

1. Search Consent

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

Search Parameters:

Name	Type	Description
patient	Reference	Patient Identifier
_lastUpdated	Date
_offset	Number	Used for Pagination
_count	Number	Used for Pagination

Consent Search Examples

1.1 Retrieve Consent records by patient

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

2. Create Consent (if authorization does not exist)

HTTP Request	Method	Action
/Consent	POST	Creates Consent resource

The following attributes are required:

Name	Details
patient
source
sourceAttachment

The following attributes are supported:


identifier
status
category
period
dateTime
actor	Author, Verifier, or Custodian

{
	"resourceType": "Consent",
	"status": "active",
	"category": [
		{
			"coding": [
				{
					"system": "http://loinc.org",
					"code": "64292-6"
				}
      ]
    }
  ],
	"patient": {
		"reference": "Patient/xxx"
	},
	"period": {
		"start": "xxx",
		"end": "xxx"
	},
	"sourceAttachment": {
		"contentType": "application/pdf",
		"data": "base64 encoded data",
		"title": "Authorization form"
	}
}

3. Read Consent

HTTP Request	Method	Action
/Consent/{ID}	GET	Retrieve Consent Resource by FHIR resource ID

4. Delete Consent

This function may be used if the authorization has been revoked by the patient, or if the existing authorization forms needs to be updated. If you are updating the authorization, first delete the existing authorization and then create a new authorization using the Create Authorization method above.

HTTP Request	Method	Action
/Consent/{ID}	DELETE	Deletes the Consent resource

Initialize Chart Bridge

Health Gorilla connects to multiple networks and the $init-chartbridge-enrollment endpoint queries all networks from a single call, based on your permitted purposes and licensing. This query may be completed within 5 minutes but some requests may take up to 5 days.

Supported Query Parameters

Name	Value	Description
patient	RESOURCE_ID	The Patient Resource ID. Required
consent	RESOURCE_ID	The Consent Resource ID. Required.

Chart Bridge Query/Response Examples

Query for the person's details matching the given patient ID and consent forms.

https://api.healthgorilla.com/fhir/Patient/{patientID}/$init-chartbridge-enrollment?consent={ConsentID}

Chart Bridge Query Response

The operation returns an identifier for the request.

{
    "resourceType": "OperationOutcome",
    "id": "7fcfde623d78bb6bf6b99063"
}

After a successful query is created, the user will be able to retrieve the document references in as soon as 5 minutes but some request may take up to 5 days.

Retrieve Patient Clinical Data

The patient's clinical data can be retrieved by querying for actual clinical documents using the DocumentReference endpoint or for individual FHIR resources using Health Gorilla's suite of FHIR API's

DocumentReference FHIR Operations

DocumentReference is metadata describing documents such as CDA, FHIR documents, results, clinical notes, etc. Retrieving the DocumentReference resource helps identify which documents are available for retrieval. The DocumentReference query returns a list of available documents.

https://api.healthgorilla.com/fhir/R4/DocumentReference

1. Search DocumentReference endpoint

HTTP Request	Method	Action
/DocumentReference?[parameter={value}]	GET	Retrieve the DocumentReference resource based on the search parameters.

Search parameters:

Name	Type	Description
patient	Reference	Patient FHIR Resource ID
type	Token	Kind of Document
class	Token	Categorization of document
_lastUpdated	Date

DocumentReference Query/Response Examples

1.1 Retrieve all DocumentReference metadata by patient

https://api.healthgorilla.com/fhir/R4/DocumentReference?patient={patientID}

1.2 Retrieve all DocumentReference metadata for a specific patient that were updated in August 2018

https://api.healthgorilla.com/fhir/R4/DocumentReference?patient={patientID}&_lastUpdated=2018-08

1.3 DocumentReference Response Example

The response payload will contain unique URL's for each document that will be used to download the actual document in the next step. The URL is contained in the 'content' field of the response payload.

"content": [
                    {
                        "attachment": {
                            "contentType": "text/xml",
                            "url": "https://sandbox.healthgorilla.com/fhir/Binary/12ee5b632d6535833dbe68a8",
                            "size": 1183424,
                            "hash": "QjcwOTg0QjNGMjQ3NEE3M0QxNjdGRkMzQTA4QzMwRTk=",
                            "title": "JoeGorillaCCD.xml"
                        },
                        "format": {
                            "system": "urn:oid:1.3.6.1.4.1.19376.1.2.3",
                            "code": "urn:ihe:pcc:xphr:2007",
                            "display": "HL7 CCD Document"
                        }
                    }
                ]

2. Retrieve Select Documents

After using the retrieve operation for DocumentReference, the next step is to retrieve the document itself by downloading its content using the URL(s) found in the response payload from the previous step. The DocumentReference.content.attachment field from the payload contains the URL to the actual document. The DocumentReference.attachment.contentType field from the payload contains the MIME type of the document. Health Gorilla provides an endpoint that is used to download binary content. This endpoint represents a FHIR Binary resource. See https://www.hl7.org/fhir/binary.html for details.

An 'Accept' header is required to be set. You can pass either 'Accept Any' or pass the MIME type specified in the DocumentReference.attachement.contentType field field from the response payload.

The result of this call is HTTP 200 OK.

GET /api/Binary/BINARY_RESOURCE_ID HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787
Accept: text/html

Retrieve all information related to a given Patient ($everything)

Health Gorilla implements FHIR $everything operation that can be used to retrieve all the information related to the given patient. The payload consists of FHIR resources representing all data on the given patient.

HTTP Request	Method	Action
/Patient/{ID}/$everything	GET	Read all records related to the specified patient

Search parameters:

Name	Type	Description
start	date	The date range relates to care dates. Return all records relating to care provided in a certain date range
end	date	The date range relates to care dates. Return all records relating to care provided in a certain date range.
_since	datetime	Resources updated after this period will be included in the response.
_type	code	One or more parameters, each containing one or more comma-delimited FHIR resource types to include in the return resources.

$everything Examples

Return all information for the specified patient:

https://api.healthgorilla.com/fhir/Patient/03db4352ee0190ad5e9e6748/$everything

Return all DiagnosticReports, Observations, Immunizations, Encounters updated since 2019-09-01

https://api.healthgorilla.com/fhir/Patient/03db4352ee0190ad5e9e6748/$everything
?_format=json
&_type=DiagnosticReport,Observation,Immunization,Encounter
&_since=2019-09-01