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
Composition
records 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 .