Composition

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 GET
  • composition.write – Required to create, update, or delete via POST, PUT, DELETE

For more information, go to: OAuth 2.0 Authentication.

Supported Methods

MethodOperationDescription
GETRead CompositionRetrieves one or more Composition documents for a patient.
GETSearch CompositionsSearches for Composition documents based on specified criteria.
GETDocument CompositionRetrieves a Composition document along with all related data in a single Bundle.

Frequently Used Search Parameters

ParameterTypeRequiredDescription
patientstringYesFilters by patient ID (Patient/{id})
encounterstringNoFilters by associated encounter ID (Encounter/{id})
typestringNoFilters by document type (LOINC)
statusstringNoFilters by composition status (CompositionStatus)
authorstringNoFilters by the authoring practitioner or organization

Commonly Returned Resource Attributes

AttributeDescriptionExample ValuesFHIR Data TypeRequired
idLogical ID of the compositionComposition/45678idYes
statusWorkflow status of the documentfinal, preliminary, amendedcodeYes
typeKind of clinical document (LOINC-coded)18842-5 (Discharge Summary)CodeableConceptYes
categoryClassification of the documentsummary, report, letterCodeableConcept[]No
subjectPatient the composition applies toPatient/12345Reference(Patient)Yes
encounterRelated clinical encounterEncounter/67890Reference(Encounter)No
dateWhen the document was authored2024-03-15T10:00:00ZdateTimeYes
authorWho authored the compositionPractitioner/abc123`Reference(PractitionerOrg)`Yes
titleHuman-readable title"Discharge Summary – Cardiology"stringNo
attesterWho attested to the accuracy of the documentPractitioner/att123Reference(Practitioner)No
sectionNested 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 .

Additional Resources

FHIR R4: Composition