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

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

Search Parameters:

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

The following attributes are required:

The following attributes are recommended:

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

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.

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:

Consent FHIR Operations

The following FHIR operations are currently supported:

1. Search Consent

Search Parameters:

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)

The following attributes are required:

The following attributes are supported:

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

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.

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

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

Search parameters:

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.

Search parameters:

$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