Chart Bridge
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
- FHIR http://hl7.org/fhir/
- SMART on FHIR http://docs.smarthealthit.org/
- Health Gorilla Clinical Network OAuth 2.0 Guide
- Health Gorilla FHIR RESTful API specification
- Health Gorilla FHIR Profiles
- Health Gorilla FHIR Extensions
- Health Gorilla FHIR Value Sets
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

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 |
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
Updated 2 days ago