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

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 RequestMethodAction
/Patient?[parameter={value}]GETRetrieve the Individual Patient resources meeting the specified search criteria.

Search Parameters:

NameTypeDescription
identifierTokenIndividual's Identifier (MRN)
familyStringIndividual's Family Name
givenStringIndividual's Given Name
birthdateStringIndividual's DOB (in YYYY-MM-DD format)
genderTokenIndividual's Gender (male/female)
address-postalcodeStringIndividual's Postal (zip) code
_lastUpdatedDate
_offsetNumber
_countNumber

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 RequestMethodAction
/PatientPOSTCreates patient resource for the individual.

The following attributes are required:

NameDescription
givenIndividual's given name
familyIndividual's family name
birthdateIndividual's DOB (in YYYY-MM-DD format)
genderIndividual's Gender (male/female)
addressPostal 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:

NameDescription
phone numbertelecom in FHIR Patient Resource
emailtelecom 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 RequestMethodAction
/Patient/{ID}GETRetrieve 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 RequestMethodAction
/Patient/{ID}PUTUpdates 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:

NameDescription
identifierFHIR ID of the Consent Resource
categoryClassification of Consent Statement
patientWho the consent applies to
periodTimeframe for this rule
dateTimeWhen the consent was created or indexed
actorAuthor, Verifier or Custodian
sourceAttachmentConsent Documentation

Consent FHIR Operations

The following FHIR operations are currently supported:

1. Search Consent

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

Search Parameters:

NameTypeDescription
patientReferencePatient Identifier
_lastUpdatedDate
_offsetNumberUsed for Pagination
_countNumberUsed 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 RequestMethodAction
/ConsentPOSTCreates Consent resource

The following attributes are required:

NameDetails
patient
source
sourceAttachment

The following attributes are supported:

identifier
status
category
period
dateTime
actorAuthor, 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 RequestMethodAction
/Consent/{ID}GETRetrieve 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 RequestMethodAction
/Consent/{ID}DELETEDeletes 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

NameValueDescription
patientRESOURCE_IDThe Patient Resource ID. Required
consentRESOURCE_IDThe 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 RequestMethodAction
/DocumentReference?[parameter={value}]GETRetrieve the DocumentReference resource based on the search parameters.

Search parameters:

NameTypeDescription
patientReferencePatient FHIR Resource ID
typeTokenKind of Document
classTokenCategorization of document
_lastUpdatedDate

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 RequestMethodAction
/Patient/{ID}/$everythingGETRead all records related to the specified patient

Search parameters:

NameTypeDescription
startdateThe date range relates to care dates. Return all records relating to care provided in a certain date range
enddateThe date range relates to care dates. Return all records relating to care provided in a certain date range.
_sincedatetimeResources updated after this period will be included in the response.
_typecodeOne 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