The FHIR R4 Composition resource represents a set of healthcare-related documents or a summary of a patient's clinical history. It is used to structure documents such as discharge summaries, progress notes, or other collections of related information.
Use Cases
- Retrieve structured clinical documents associated with an encounter or hospital stay
- Create new
Compositionrecords representing discharge summaries or continuity of care documents - Update existing documents with new observations or metadata
- Delete incorrect or outdated compositions
- Filter compositions by patient, type, author, or encounter
Base URLs
- Production:
https://api.healthgorilla.com/fhir/R4/Composition - Sandbox:
https://sandbox.healthgorilla.com/fhir/R4/Composition
Authentication
All requests require OAuth 2.0 authentication using a Bearer Token. Unauthorized requests return 401 Unauthorized responses.
Required Scopes
composition.read– Required to retrieve Composition records via GETcomposition.write– Required to create, update, or delete via POST, PUT, DELETE
For more information, go to: OAuth 2.0 Authentication.
Supported Methods
| Method | Operation | Description |
|---|---|---|
GET | Read Composition | Retrieves one or more Composition documents for a patient. |
GET | Search Compositions | Searches for Composition documents based on specified criteria. |
GET | Document Composition | Retrieves a Composition document along with all related data in a single Bundle. |
Frequently Used Search Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
patient | string | Yes | Filters by patient ID (Patient/{id}) |
encounter | string | No | Filters by associated encounter ID (Encounter/{id}) |
type | string | No | Filters by document type (LOINC) |
status | string | No | Filters by composition status (CompositionStatus) |
author | string | No | Filters by the authoring practitioner or organization |
Commonly Returned Resource Attributes
| Attribute | Description | Example Values | FHIR Data Type | Required | |
|---|---|---|---|---|---|
id | Logical ID of the composition | Composition/45678 | id | Yes | |
status | Workflow status of the document | final, preliminary, amended | code | Yes | |
type | Kind of clinical document (LOINC-coded) | 18842-5 (Discharge Summary) | CodeableConcept | Yes | |
category | Classification of the document | summary, report, letter | CodeableConcept[] | No | |
subject | Patient the composition applies to | Patient/12345 | Reference(Patient) | Yes | |
encounter | Related clinical encounter | Encounter/67890 | Reference(Encounter) | No | |
date | When the document was authored | 2024-03-15T10:00:00Z | dateTime | Yes | |
author | Who authored the composition | Practitioner/abc123 | `Reference(Practitioner | Org)` | Yes |
title | Human-readable title | "Discharge Summary – Cardiology" | string | No | |
attester | Who attested to the accuracy of the document | Practitioner/att123 | Reference(Practitioner) | No | |
section | Nested content sections (with entries, title, code) | section[0].title = "Medications" | BackboneElement[] | No |
Webhooks
To receive notifications when new Composition records are added or updated, clients can subscribe using the FHIR Subscription resource with filters such as Composition?status=final. For more information, go to: Webhooks & Polling.
Error Handling
All Composition operations follow standard Health Gorilla error handling practices using the FHIR OperationOutcome structure. For more information, go to: Error Handling.