The FHIR R4 DocumentReference resource represents metadata about clinical documents such as C-CDAs, PDFs, imaging reports, and other unstructured records.
In Health Gorilla, DocumentReference is used to discover and access patient documents aggregated from multiple clinical data sources. It is the primary resource used to locate and retrieve document-based clinical data.
Overview
DocumentReference provides:
- Metadata about a document (type, author, date, status)
- References to the patient associated with the document
- Links to the actual document content via
content.attachment.url
It does not contain the document itself. To retrieve the document content, use the Binary endpoint referenced in the attachment.
Common Use Cases
- Retrieve clinical documents for a patient
- Discover available documents before retrieval
- Access diagnostic reports, clinical notes, and discharge summaries
- Download document content (PDF, CDA, images)
- Support care coordination and transitions
HG-Specific Behavior
- Documents may originate from multiple external networks and sources
- Document metadata is normalized across sources for consistent access
- Not all documents are fully structured or coded
- Document content is accessed separately via the Binary endpoint
- Some document retrieval workflows may involve asynchronous processing
Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type |
|---|---|---|---|
subject | Patient associated with the document | Patient/{id} | Reference(Patient) |
status | Status of the document reference | current, superseded | code |
type | Type of document | clinical-note, discharge-summary | CodeableConcept |
category | Classification of the document | clinical-note, imaging | CodeableConcept[] |
date | Document creation or indexing date | 2024-02-12T12:34:56Z | dateTime |
author | Author of the document | Practitioner/{id} | Reference[] |
content | Attachment metadata including document access URL | Binary/{id} | BackboneElement[] |
Retrieve Documents
Search Documents
GET /fhir/R4/DocumentReference?patient={id}Returns a Bundle of DocumentReference resources matching the search criteria.
Retrieve by ID
GET /fhir/R4/DocumentReference/{id}Returns a single DocumentReference.
Operations
Download Document Content
To retrieve the actual document file, use the Binary endpoint referenced in:
content[].attachment.urlExample:
GET /fhir/R4/Binary/{id}
Authorization: Bearer {access_token}Notes:
- Binary content may be protected or time-limited
- The required scope is typically the same as the referencing resource (for example,
documentreference.read)
Search Behavior
- Searches are scoped to the authenticated tenant
- The
patientparameter is required for most queries - Results are returned as a FHIR Bundle
- Pagination is supported via
Bundle.link
Search Parameters
A document search must be bounded. Supply at least one of patient, type, category, or _lastUpdated. A request with none of them is rejected.
| Parameter | Required | Description |
|---|---|---|
patient | No | The patient whose documents you want, as Patient/{id}. You can also search by a patient identifier using patient.identifier. |
type | No | Filters on the document type. |
category | No | Filters on the document category. In STU3 this parameter is named class. |
date | No | Filters on DocumentReference.date, the time the document reference was created, rather than the period of care the document describes. |
custodian | No | Returns documents held by the given organization, as Organization/{id}. |
_lastUpdated | No | Filters on when the record was last written in the Health Gorilla FHIR server. Accepts a comparison prefix, for example ge2025-01-01. |
_offset | No | Skips the given number of results. |
_count | No | Limits the number of results returned per page. |
_tag | No | Filters on meta.tag. |
_security | No | Filters on meta.security. |
The search also accepts _include=DocumentReference:subject and _include=Coverage:beneficiary to return referenced resources.
Authentication
All requests require OAuth 2.0 bearer token authentication.
Required scopes:
documentreference.readfor read operationsdocumentreference.writefor create, update, and delete operations
For more information, see: OAuth 2.0 Authentication
Notifications
The FHIR R4 API does not provide direct subscriptions for DocumentReference.
Document updates may be available through broader event or notification workflows depending on configuration.
Error Handling
All operations return standard FHIR OperationOutcome responses for errors.
For more information, see: Error Handling
Related Resources
- Binary: Retrieve document content
- Patient: Associated patient record
- Provenance: Source and origin of documents