Documents and Files

Health Gorilla APIs support the retrieval of clinical documents that contain both structured and unstructured content, including Consolidated Clinical Document Architecture (C-CDA) records, PDFs, and scanned faxes. C-CDAs combine computable, coded data with human-readable narrative text, making them suitable for automated processing and clinician review. These documents are represented using the FHIR DocumentReference and Binary resources.

DocumentReference Resource

Use the DocumentReference resource to search for and retrieve metadata about clinical documents.

Common attributes include:

type: Coded classification such as discharge summary, referral note, or lab report
date: Service date or document creation date
custodian: Organization responsible for the document
status: Verification and availability status
content.attachment.url: Direct link to the associated Binary payload
identifier: External or system-specific identifier for cross-system referencing
category: Optional grouping (e.g., clinical-note, imaging) for faster filtering

Binary Resource

The Binary resource stores the full document content. Payloads are returned in the original format and encoded as required.

Supported types include:

C-CDA or CDA XML documents
Scanned reports and faxes in PDF
Image and plain-text payloads encoded in Base64

Access to Binary content is governed by the associated DocumentReference and requires a valid access token.

Best Practices

Use DocumentReference to filter and locate relevant documents before accessing the Binary
Filter queries using type, date, or custodian for optimal performance
Monitor payload size and download volume when retrieving PDFs, images, or large files
Prefer C-CDA documents over scanned PDFs when structured, computable data is needed
Preserve all returned metadata (including system URIs and coding) to maintain interoperability and audit trails