The FHIR R4 Bundle resource is used to group multiple FHIR resources together into a single container for transport and processing. Bundles enable clients to submit, retrieve, or process collections of related resources as a single unit, supporting batch, transaction, and document-based workflows.
Health Gorilla exposes the Bundle resource as part of its FHIR R4 API to support composite operations that involve multiple resources within a single request or response.
Use Cases
- Submitting multiple related resources in a single request using batch or transaction processing
- Performing atomic create or update operations across multiple resources
- Retrieving grouped clinical data returned as part of search or
$everythingoperations - Packaging clinical documents composed of multiple interrelated resources
Scope and Behavior
This documentation describes the FHIR R4 API interface for the Bundle resource. Health Gorilla’s platform may use additional internal services and processing logic to validate, normalize, and route bundled content. Only the FHIR R4–exposed behavior is documented here.
Health Gorilla supports a subset of HL7 FHIR R4 Bundle capabilities based on the bundle type and operation context. Not all bundle types or processing modes defined in the HL7 specification may be supported. Unsupported bundle types or invalid entries may result in request rejection or partial processing, depending on the operation.
In Health Gorilla, developers most commonly interact with Bundle in two ways: (1) as the response container returned by FHIR searches and other multi-resource operations, and (2) as the request body for composite write operations using batch or transaction processing.
Bundle Types
The type element determines how a Bundle is processed. Common bundle types include:
| Type | Description |
|---|---|
batch | A collection of independent operations processed separately, with individual responses returned |
document | A structured clinical document composed of multiple related resources |
transaction | A set of operations processed atomically; all operations must succeed or the entire transaction fails |
Health Gorilla primarily supports batch and transaction Bundles for write operations. searchset bundles are returned for search responses. Document Bundles may be returned as part of retrieval scenarios, , depending on configuration and upstream source behavior.
Authentication
All requests to the FHIR R4 API require OAuth 2.0 authentication using a bearer token. Unauthorized requests return a 401 Unauthorized response.
Required Scopes
bundle.write for POST
For more information, go to: OAuth 2.0 Authentication.
Supported Methods
| Method | Operation | Description |
|---|---|---|
POST | Submit Bundle | Processes a batchor transaction Bundle submitted in the request body |
Processing Behavior
Bundleprocessing for supported batch and transaction operations is synchronous.- For
batchBundles, each entry is processed independently, and partial success is possible. - For
transactionBundles, all included operations must succeed for the transaction to complete. - Responses are returned as a
Bundlecontaining the outcome of each operation.
Error Handling
All Bundle operations use standard Health Gorilla error handling and return a FHIR OperationOutcome resource for structured error details when failures occur. For more information, go to: Error Handling .