Patient Access API

Suggest Edits

This API allows facilities to send requests the Health Gorilla Clinical Network on behalf of the patient to retrieve their medical documents and import them into Health Gorilla. These requests are under the permitted purpose of Individual Access Services or Patient Access Request.

Prerequisites

  1. "Requested" patient must exist in the facility
  2. Requested patient must pass IAL2 identity check before the call. See IAL2 Identity Verification iframe API.
  3. All API methods are executed in the context of a session, created for the user which is determined by OAuth token with the following requirements:
  • OAuth client scope include 'patient_request'

Note that requests from deceased patients is not supported and will return an error.

Enroll and Import All Patient Documents

This operation will import all new person's documents from the Health Gorilla Clinical Network. Any documents that have been previously imported and identified as duplicates are excluded.

This operation can take a long time to complete, therefore it must be performed asynchronously.

Note: One of the connected networks includes CommonWell. This operation will link HG patient with a new or existing CommonWell person. If there is no single matching person in CommonWell, an error is returned.

{portalURL}/Patient/{patientId}/$patient-enroll-import-docs
FieldDecription
patientIDPatient resource ID (Required)

Selectively Download and Import Documents

If you want to preview the documents prior to importing or want to selectively import documents, the $patient-enroll-retrieve-docs allows you to preview the documents metadata.

Enroll and Get Documents Metadata

Returns a bundle with documents metadata from the Health Gorilla Clinical Network for the patient.

This operation can take a long time to complete, therefore it must be performed asynchronously.

Note: One of the connected networks includes CommonWell. This operation will link HG patient with a new or existing CommonWell person. If there is no single matching person in CommonWell, an error is returned.

{portalURL}/Patient/{patientId}/$patient-enroll-retrieve-docs

Parameters:

FieldDescription
patientIdPatient resource ID (Required)

Download a Document

Retrieves document content by the link. Link is a value from DocumentReference resource: content[].attachment.url

Use $patient-enroll-retrieve-docs to get the links.

{portalURL}/Patient/{patientId}/$retrieve-document?resource={resourceParam}

Parameters:

FieldDescription
patientIdPatient resource ID (Required)
resourceParamLink that is used to download the given document (Required)

Import a Document

Imports the given document from the HG Clinical Network into your facility.

This operation can take a long time to complete, therefore it must be performed asynchronously.

{portalURL}/Patient/{patientId}/$patient-import-doc

Parameters:

FieldDescription
patientIdPatient resource ID (Required)
fhirDocumentReferenceFHIR DocumentReference to import, located n the body of the request. (Required)

The following fields are required:
- subject
- content
- content.attachment
- content.attachment.url

Health Gorilla provides two different ways to import selected documents:

  • import a single document
  • import a batch of documents

📘

Note

If you import a CDA document (clinical note, transfer note etc.) then all embedded medical history records will be attached to the corresponding patient chart.

🚧

Regardless of the method you choose be aware that the import process could take a significant amount of time due to communication delays while we fetching the original document from its source. So you must request in an asynchronous manner.

Import a single document

In order to import a single document you should send HTTP POST request to the DocumentReference endpoint and supply the selected DocumentReference resource as a payload.

You can find the detailed operation description in FHIR Restful API Guide.

The synchronous version of this operation is below:

POST /fhir/DocumentReference HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787
HG-Idempotency-Key: 15e72676-48c3-11ea-b77f-2e728ce88125
Content-Type: application/json 
[...omitted for brevity...]

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796
Location: https://api.healthgorilla.com/fhir/DocumentReference/a690435f1528380fc5d18479
Content-Length: 0
Date: Tue, 25 aug 2020 12:15:01 GMT

{ 
   "resourceType":"DocumentReference",
   "meta":{ 
      "profile":[ 
         "https://healthgorilla.com/fhir/StructureDefinition/hg-cw-document"
      ]
   },
   "masterIdentifier":{ 
      "system":"urn:ietf:rfc:3986",
      "value":"5fb4315db0e647bd6e38c1a6"
   },
   "identifier":[ 
      { 
         "use":"official",
         "system":"urn:ietf:rfc:3986",
         "value":"urn:uuid:b558f5eb-4276-4597-bbe8-c8fb456ead60"
      }
   ],
   "status":"current",
   "type":{ 
      "coding":[ 
         { 
            "system":"http://loinc.org/",
            "code":"34133-9",
            "display":"Summarization of episode note"
         }
      ]
   },
   "class":{ 
      "coding":[ 
         { 
            "system":"http://loinc.org/",
            "code":"34133-9",
            "display":"Summarization of episode note"
         }
      ]
   },
   "subject":{ 
      "reference":"Patient/fa6a2e5dc18ac1d18b64f618",
      "display":"Tom Sower"
   },
   "created":"2020-02-13T06:55:35+00:00",
   "indexed":"2020-02-13T06:55:35.000+00:00",
   "description":"Continuity of Care Document",
   "securityLabel":[ 
      { 
         "text":"Normal"
      }
   ],
   "content":[ 
      { 
         "attachment":{ 
            "contentType":"text/xml",
            "language":"en-us",
            "url":"https://api.healthgorilla.com/fhir/Binary/sample"
         },
         "format":{ 
            "code":"urn:ihe:pcc:xphr:2007"
         }
      }
   ],
   "context":{ 
      "facilityType":{ 
         "coding":[ 
            { 
               "system":"http://snomed.info/sct",
               "code":"83891005",
               "display":"Solo practice private office"
            }
         ]
      }
   }
}

Import a batch of documents

In order to import a batch of documents into your Health Gorilla account, you should send HTTP POST request to the Bundle endpoint and supply selected DocumentsReference resources packaged in a Bundle of type “batch” as a payload.

This is a two-step operation in which first you need to submit a batch of documents and then send a second request to read the operation outcome.

You can find the detailed description in FHIR Restful API Guide.

The synchronous version of this operation is below:

POST /fhir/Bundle HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787
HG-Idempotency-Key: 15e72676-48c3-11ea-b77f-2e728ce88125
Content-Type: application/json 
[...omitted for brevity...]

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796
Location: https://api.healthgorilla.com/fhir/Bundle/9146293b-a1e4-446b-b692-faa929ea8725
Content-Length: 0
Date: Tue, 25 Aug 2020 09:09:55 GMT

{
  "resourceType": "Bundle",
  "id": "batch",
  "type": "batch",
  "entry": [
    {
      "fullUrl": "urn:uuid:7f9724ed-ef8d-4434-aacb-41869db83233",
      "resource": {
        "resourceType": "DocumentReference",
        "meta": {
          "profile": [
            "https://healthgorilla.com/fhir/StructureDefinition/hg-cq-document"
          ]
        },
        "contained": [
          {
            "resourceType": "Organization",
            "id": "1",
            "identifier": [
              {
                "type": {
                  "coding": [
                    {
                      "code": "hcid",
                      "display": "Home Community ID"
                    }
                  ],
                  "text": "Home Community ID"
                },
                "value": "1.3.6.1.4.1.52618.2.3120"
              }
            ],
            "name": "Test Practice 360-2"
          }
        ],
        "extension": [
          {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/documentreference-ondemand",
            "valueBoolean": true
          }
        ],
        "status": "current",
        "type": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "34133-9",
              "display": "Summarization of episode note"
            }
          ]
        },
        "class": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "34133-9",
              "display": "Summarization of episode note"
            }
          ]
        },
        "subject": {
          "reference": "Patient/96afb95c241be840030d7072",
          "display": "Joe Test"
        },
        "created": "2020-08-20T08:11:15+00:00",
        "indexed": "2020-08-20T08:11:15.000+00:00",
        "custodian": {
          "reference": "#1",
          "display": "Sacred health Hospital"
        },
        "description": "Continuity of Care Document",
        "content": [
          {
            "attachment": {
              "contentType": "text/xml",
              "url": "https://api.healthgorilla.com/fhir/Binary/cq-6NPeUyZWgSxfJzdc0XqJJdLLwGn3sMAAxlC4D_BhEe1ZcwF-ahhG4LrU0q-luDzpUKfhey9HJt9KChIpsxXmz-BPakWzSN5po1wLCah5U3230ndfLdjIIDHAdC_Th5NphXURzt-qGyyE-GUmqowRTjmML99ugWJv6VKwU1H57lTrnsyf0YSJ4h89AqhOz9xdnKq-hBDKQT5R35IeRX5qNBiAxEkHLeILwIZ7C-_hcKuMHHkAVV7lLRJydRAtqMjvluBQzd1kdUesi99POexK28VLa5vHhmZoVOmS0s9X3t42LsZrkQ8-cflqejeJmwi5fqET18Mt94hbV4hUuEPoDOU1dHSM6W23Qg8rWHzhF6znfR10fzw0RLO4ig9UUPuM"
            }
          }
        ]
      }
    },
    {
      "fullUrl": "urn:uuid:d5d0848a-6610-4053-8663-42a8c9423a13",
      "resource": {
        "resourceType": "DocumentReference",
        "meta": {
          "profile": [
            "https://healthgorilla.com/fhir/StructureDefinition/hg-cq-document"
          ]
        },
        "contained": [
          {
            "resourceType": "Organization",
            "id": "1",
            "identifier": [
              {
                "type": {
                  "coding": [
                    {
                      "code": "hcid",
                      "display": "Home Community ID"
                    }
                  ],
                  "text": "Home Community ID"
                },
                "value": "1.3.6.1.4.1.52618.2.6572"
              }
            ],
            "name": "Dr. John M Doe, MD Practice"
          }
        ],
        "extension": [
          {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/documentreference-ondemand",
            "valueBoolean": true
          }
        ],
        "status": "current",
        "type": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "34133-9",
              "display": "Summarization of episode note"
            }
          ]
        },
        "class": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "34133-9",
              "display": "Summarization of episode note"
            }
          ]
        },
        "subject": {
          "reference": "Patient/96afb95c241be840030d7072",
          "display": "Joe Test"
        },
        "created": "2020-08-20T08:11:23+00:00",
        "indexed": "2020-08-20T08:11:23.000+00:00",
        "custodian": {
          "reference": "#1",
          "display": "Dr. John M Doe, MD Practice"
        },
        "description": "Continuity of Care Document",
        "content": [
          {
            "attachment": {
              "contentType": "text/xml",
              "url": "https://api.healthgorilla.com/fhir/Binary/cq-6NPeUyZWgSxfJzdc0XqJJdLLwGn3sMAAxlC4D_BhEe2iYsFGdA0MMMrVf0i0d2c_uMPOZfOiE7L5gHXPnlAtTeBPakWzSN5po1wLCah5U3230ndfLdjIIDHAdC_Th5NphfZ4cI-lTNkSK8qdz27_2zmML99ugWJv6VKwU1H57lTrnsyf0YSJ4h89AqhOz9xdnKq-hBDKQT5R35IeRX5qNBiAxEkHLeILwIZ7C-_hcKuMHHkAVV7lLRJydRAtqMjvluBQzd1kdUesi99POexK26vcnNsWQFV01bJm2bMyggc2LsZrkQ8-cflqejeJmwi5fqET18Mt94hbV4hUuEPoDOU1dHSM6W23Qg8rWHzhF6znfR10fzw0RLO4ig9UUPuM"
            }
          }
        ]
      }
    },
    {
      "fullUrl" : "urn:uuid:046751b9-210c-4bbf-a914-ec742fd71fc5",
      "resource": {
        "resourceType": "DocumentReference",
        "meta": {
          "profile": [
            "https://healthgorilla.com/fhir/StructureDefinition/hg-cq-document"
          ]
        },
        "contained": [
          {
            "resourceType": "Organization",
            "id": "1",
            "identifier": [
              {
                "type": {
                  "coding": [
                    {
                      "code": "hcid",
                      "display": "Home Community ID"
                    }
                  ],
                  "text": "Home Community ID"
                },
                "value": "1.3.6.1.4.1.52618.2.2634"
              }
            ],
            "name": "Test Practice"
          }
        ],
        "extension": [
          {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/documentreference-ondemand",
            "valueBoolean": true
          }
        ],
        "status": "current",
        "type": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "34133-9",
              "display": "Summarization of episode note"
            }
          ]
        },
        "class": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "34133-9",
              "display": "Summarization of episode note"
            }
          ]
        },
        "subject": {
          "reference": "Patient/96afb95c241be840030d7072",
          "display": "Joe Test"
        },
        "created": "2020-08-20T08:11:26+00:00",
        "indexed": "2020-08-20T08:11:26.000+00:00",
        "custodian": {
          "reference": "#1",
          "display": "Test Practice 360-5"
        },
        "description": "Continuity of Care Document",
        "content": [
          {
            "attachment": {
              "contentType": "text/xml",
              "url": "https://api.healthgorilla.com/fhir/Binary/cq-6NPeUyZWgSxfJzdc0XqJJdLLwGn3sMAAxlC4D_BhEe0D2VnjtdjjcP_6P63ieJahnMTyDdPu14CmHMV0h2a-nOBPakWzSN5po1wLCah5U3230ndfLdjIIDHAdC_Th5Np1Hu8jsc7ffgh5m7hewkg9DmML99ugWJv6VKwU1H57lTrnsyf0YSJ4h89AqhOz9xdnKq-hBDKQT5R35IeRX5qNBiAxEkHLeILwIZ7C-_hcKuMHHkAVV7lLRJydRAtqMjvluBQzd1kdUesi99POexK2yVRNJAnzssJayeYaDH2OUA2LsZrkQ8-cflqejeJmwi5fqET18Mt94hbV4hUuEPoDOU1dHSM6W23Qg8rWHzhF6znfR10fzw0RLO4ig9UUPuM"
            }
          }
        ]
      }
    }
  ]
}

{
    "resourceType": "Bundle",
    "type": "batch-response",
    "total": 3,
    "entry": [
        {
            "fullUrl": "urn:uuid:7f9724ed-ef8d-4434-aacb-41869db83233",
            "response": {
                "status": "201 Created",
                "location": "/fhir/DocumentReference/40333e5f892edf9999e78973"
            }
        },
        {
            "fullUrl": "urn:uuid:d5d0848a-6610-4053-8663-42a8c9423a13",
            "response": {
                "status": "201 Created",
                "location": "/fhir/DocumentReference/42333e5fca0f80adf9ca0042"
            }
        },
        {
            "fullUrl": "urn:uuid:046751b9-210c-4bbf-a914-ec742fd71fc5",
            "response": {
                "status": "201 Created",
                "location": "/fhir/DocumentReference/44333e5f9fe634e0740e455a"
            }
        }
    ]
}
Converting a search set to a batch:

The search operation outcome is a Bundle of type ‘searchset’. And if you want to import all of these documents then you need to convert it to a Bundle of type ‘batch’.
a) Change the Bundle.type to ‘batch’
b) Remove the following attributes

  • Bundle.meta
  • Bundle.total
  • Bundle.link

c) Add the Bundle.entry.fullUrl parameter to an each entry

"fullUrl":"urn:uuid:UUIDV4"

Then you can import this Bundle to your Health Gorilla account.

Unenroll a Patient

One of the connected networks includes CommonWell. This operation unlinks and unenrolls the given patient from the CommonWell network. If the patient is not linked with a CommonWell person, no action is taken.

{portalURL}/Patient/{patientId}/$facility-patient-cw-unenroll

Parameters:

FieldDescription
patientIdPatient resource ID (Required)

Updated 5 months ago