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 Structure
Commonly returned attributes include:
| 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
Common Search Parameters
| Parameter | Description | Example Values | FHIR Data Type |
|---|---|---|---|
patient | Filter by patient | Patient/{id} | Reference |
status | Filter by document status | current, superseded | token |
type | Filter by document type | discharge-summary, clinical-note | token |
category | Filter by document category | clinical-note, imaging | token |
author | Filter by author | Practitioner/{id} | Reference |
date | Filter by document date | ge2024-01-01 | date |
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