Composition
Work with FHIR R4 4.0.1 Composition resources.
Choose an operation for this resource:
- Search Composition
- Read Composition
- Read Composition Version
- Create Composition
- Update Composition
- Delete Composition
- Hard Delete Composition
- Purge Deleted Composition
The diagram summarizes Composition requests and responses. See Supported FHIR REST Interactions for the shared interaction model.
FHIR R4 definition: https://hl7.org/fhir/R4/composition.html. See interaction response codes and common error responses.
Interactions and permissions
- Resource lifecycle: create, read, versioned read, update, soft deletion and version preconditions.
- PUT-as-create and restoration: creation/restoration, server-managed metadata, response headers and return preferences.
- Interaction responses: success
statuscodes. - OperationOutcome errors: common errors and response bodies.
- Batch requests: independent entry processing.
| Composition capability | Support or requirement |
|---|---|
| Conditional create | Not supported. |
| Conditional update | Not supported. |
| Transaction bundles | Not supported. |
- Authentication and Scopes: bearer tokens, scope configuration and constrained access. Required resource scopes are listed on each operation page.
- Data Deletion and Purge Operations: permanent-deletion eligibility and additional permissions.
- Hard Delete and Purge Deleted: resource endpoints and required scopes; see also shared purge guidance.
Required content and validation
For shared validation-error responses, see OperationOutcome errors.
| Composition detail | Requirement or behavior |
|---|---|
| Required content | Provide status (preliminary, final, amended, or entered-in-error), type, date (editing time), at least one author, and title. |
| Resource rule | Required primitive values can instead carry a valid extension explaining the absent value. |
| Token filters | Composition preserves identifiers, references, attestations, relationships, events, nested sections, narratives, and extensions in each resource version. |
| Token filters | A relationship requires exactly one targetIdentifier or targetReference. |
section | Each section requires text, entries, or subsections (cmp-1); emptyReason is allowed only without entries (cmp-2). |
| Patient references | Contained section entries with a known subject must agree with the section focus, inherited from the parent section or Composition subject when absent. |
| Resource rule | Read or versioned-read of an unknown resource returns 404; current reads of deleted resources return 410. |
{"resourceType":"Composition","identifier":{"system":"urn:example:composition","value":"synthetic-report"},"status":"final","type":{"coding":[{"system":"http://loinc.org","code":"11502-2"}]},"subject":{"reference":"Patient/p"},"date":"2026-10-22T10:00:00Z","author":[{"reference":"Practitioner/author"}],"title":"Synthetic genetic report"}Searches
- Search operation: endpoints, complete parameter table, supported forms and examples.
- Common Search Controls: shared controls and server-provided paging links.
- Value Types and Syntax and Comparators, Modifiers, and Chains: shared syntax. Use only the forms supported by this resource.
| Composition detail | Requirement or behavior |
|---|---|
| Resource rule | Common searches include _id and _lastUpdated. |
| Patient references | Resource searches are identifier (the single Composition.identifier), patient (Patient subjects only), type, category, status, and date (Composition editing time). |
| Date filters | Date does not search event.period or server last-updated time. |
| Token filters | Token searches accept value, system|value, |value, or system|. |
| Token filters | A token parameter accepts a single unmodified value, without comma alternatives or repeated occurrences. |
| Patient references | Patient supports literal references and the :identifier modifier, without chaining. |
| Date filters | Date and _lastUpdated accept up to two repeated bounds with eq, ne, gt, lt, ge, le, sa, eb, and ap comparators. |
| Limitations | Comma alternatives are unsupported. |
| Resource rule | Use the shared result controls for pagination, counts, and totals described in FHIR Search Parameters. |
| Resource rule | The _sort parameter is ignored. |
GET /api/fhir/r4/Composition?patient=Patient/p&type=http%3A%2F%2Floinc.org%7C11502-2&status=final&date=ge2026-01-01&date=lt2027-01-01Batch and limitations
| Composition detail | Requirement or behavior |
|---|---|
| Resource rule | Composition participates in independent R4 batch entries at POST /api/fhir/r4. |
| Resource rule | An invalid entry does not undo other successful entries. |
| Limitations | Conditional create, conditional update, and transactions are unsupported. |
| Limitations | Encounter/context, author/organization, detailed section searches, new chains, composites, full text, document generation operations, and US Core certification are outside the supported scope. |
standalone | A standalone Composition does not itself constitute a FHIR document Bundle. |