Fetch Document

The API enables the fetching of single documents by their documentId value.

Documents must be fetched one by one, using the individual documentId.

Data needed to make a Fetch Document API request are provided in the response to a Find Changes API request. They include your customerId, the patientId, the orderId, the requestId, and the documentId. This collection of values identifies an individual document and allows validation.

There are three types of documents which are reported in Changes, and available for fetching

FHIR visualization
- This is a Greenlight generated PDF rendering of the FHIR R4 data. There is only one FHIR visualization available, per Request, for fetching - it is always the most up to date view of the FHIR R4 data retrieved to-date for your Request.
  - Since there is only one FHIR visualization available for a Request, there is a way to fetch this document without having to know the documentId. See the API Reference for more details.
CDA documents (CCD, ENCOUNTER_CCD, HEALTH_SUMMARY)
- These document can be retrieved in two formats.
  - Raw XML - This is the CDA exactly as Greenlight retrieved if from the health record source. This is the default format, so if an API request for a document is made without specifying format, xml is what the Greenlight API will return.
  - PDF - This is a conversion of the xml to a PDF format, for easy reading by human eyes.
CLINICAL_DOCUMENT type documents, which come from various sources, and are usually already in a format like PDF. These cannot be converted to another format - you download them as-is.
- A typical CLINICAL_DOCUMENT would be a lab report, just as it came from the laboratory to the ordering facility.

The response from the Fetch a document call will contain a download URL which will only be valid for a short time (mins). The document can then be downloaded by exercising a GET on the URL in the response. Due to the short "time to live" on the URL, we suggest the document be downloaded immediately after receiving the download URL.

In the event a URL has expired, make another call to Fetch a document to get a new URL.

The URL for that fetch also contains a suggested file name for the document, to help your users identify it compared to others.

Here is a test example:
https://dev3-documents-presigned-url.s3.amazonaws.com/2023/HEALTH_SUMMARY_ABC_Clinic_20231225_65a15d570f6ff7af97fdfe6a.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAVVXNJY5KWLCVEVHF%2F20241106%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20241106T194337Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=49ddf0d2c29c363fde084831bb7817b5724802738fb0d4fc3920b8601673b1d7

In this test example it starts with "HEALTH_SUMMARY" and ends with ".pdf" (Everything prior to the first "?" and back to the previous "/").

The suggested file name contains the beginning of the source facility name ("ABC_Clinic" in this example) and a date we derive from the data ("20231225" in this sample). These are meant to make it easier for a user to pick a particular Encounter, for example. Encounter CCD files start with "ENCOUNTER_CCD", and then the date is particularly helpful.