P360 Retrieval API

Suggest Edits

Overview

The Patient360 retrieval API ($p360-retrieve) allows a user to retrieve a patient's clinical records from all connected national health networks. These networks include legacy networks such as CommonWell, Carequality and eHealth Exchange, as well as the established QHINs (Qualified Health Information Networks). The process for retrieving a patient's clinical records is documented below.

API Workflow

HL7 FHIR

Health Gorilla RESTful API is based on FHIR protocol version STU3 and R4. Some custom resource profiles are defined and extension mechanism is 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 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/*.* patient360

P360-Retrieve API Workflow Diagram

Patient Register/Search

Before querying for clinical records, the desired patient must exist within your tenant in Health Gorilla. If you have previously created the patient in the tenant and do not have the patient's HG ID (FHIR resource ID) stored in your system, the HG ID can be retrieved using the SEARCH Patient FHIR API. The patient's HG ID will be found in the id attribute of the Patient resource.

If the patient has not been created in your tenant in Health Gorilla, you will need to create the patient using the CREATE Patient FHIR API. Upon a successful POST, the patient's HG ID will be returned in the response header.location attribute. In the below example, 73227b65649e308d91c98824 is the HG ID of the newly created patient. 

https://sandbox.healthgorilla.com/fhir/R4/Patient/73227b65649e308d91c98824

🚧

Required Demographics

The following patient demographics are required when querying the networks:

  • First Name
  • Last Name
  • Date of Birth
  • Gender
  • Full Address

Initiating the $p360-retrieve Process

To initiate the query/retrieval of a patient's clinical records, the $p360-retrieve method will be used on the DocumentReference FHIR endpoint using the patient's HG ID. The $p360-retrieve method must be executed asynchronously by including the Prefer:respond-async header. A RequestResult URL will be returned in the response header.locationattribute. This RequestResult URL will be called to retrieve the outcome of the $p360-retrieve process. For more information, see Async Requests in Health Gorilla API.

https://sandbox.healthgorilla.com/fhir/R4/DocumentReference/$p360-retrieve
?patient=PATIENT_HG_ID

https://api.healthgorilla.com/fhir/R4/DocumentReference/$p360-retrieve
?patient=PATIENT_HG_ID

When the query is initiated, the following process will execute:

  1. If the patient is not current enrolled to a CommonWell Person record, Health Gorilla will handle enrolling the patient to any matching CommonWell Persons. More information on this process can be found in the P360 Process Overiew section of the developer guide.
  2. Based on the patient demographics, clinical records will be retrieved from the connected health networks.
  3. The clinical records will be deduplicated and imported into the patient's chart in your tenant in Health Gorilla.

Retrieving the Outcome of the Query

The RequestResult URL from the previous step must be called to retrieve the outcome of the async p360 query. Your access token should be included in the request header. The following response status codes might be returned depending on the status of the query.

  1. 202: The process is still ongoing. You should continue to query the RequestResult URL using an exponential backoff until the process is complete.
  2. 4xx: An error has occured.
  3. 200: The query has been successfully completed. The response payload will contain details of the outcome of the query including:
    1. organizationsTotal: The total organizations queried for records.
    2. documentsFound: The number of total documents found on the networks
    3. documentsImported: The number of documents imported into the patient chart in your tenant in Health Gorilla.
    4. documentsSkipped: The number of documents that were found to be duplicates and therefore skipped (not imported).
    5. documentsFailed: The number of documents that failed. Failures can occur for two reasons.
      1. There is an error in the format of the document itself and Health Gorilla was unable to parse the file.
      2. The responding organization responded with an error or Health Gorilla was unable to retrieve the document from the responding organization.
    6. Organization level information

Updated 5 months ago