FHIR Bundle Types Explained: transaction, batch, searchset, document, message and more
What each FHIR Bundle.type means, the rules the spec enforces for it, how servers process transactions and batches, and the mistakes validators catch.
By the FHIR Toolbox team, Omindra Labs · 6 min read ·
Checked against the official specifications listed under Standards and references at the end of this article.
A Bundle is a container of resources, but the type element changes what the container *means*. The same three resources can be a document a clinician signed, a transaction a server must apply atomically, or just a collection someone exported. Choosing the wrong type is one of the most common reasons a server rejects an otherwise valid payload.
The Bundle types at a glance
type | Who creates it | Meaning | entry.request | entry.response |
|---|---|---|---|---|
document | Client | A signed, persistent clinical document; first entry is a Composition | not allowed | not allowed |
message | Client | A message for messaging workflows; first entry is a MessageHeader | not allowed | not allowed |
transaction | Client | Apply all entries atomically — all succeed or none do | required | not allowed |
transaction-response | Server | Outcome of a transaction | not allowed | required |
batch | Client | Apply each entry independently | required | not allowed |
batch-response | Server | Per-entry outcomes of a batch | not allowed | required |
searchset | Server | Results of a search | not allowed | not allowed |
history | Server | Versions of resources over time | required | required |
collection | Anyone | A set of resources with no processing rules | not allowed | not allowed |
subscription-notification | Server | A notification for a topic-based subscription (R5 only) | not allowed | not allowed |
These columns come straight from the Bundle invariants: bdl-3 (request is mandatory for batch, transaction and history, and prohibited otherwise) and bdl-4 (response is mandatory for batch-response, transaction-response and history, and prohibited otherwise). Two more catch people often: bdl-1 (total only in searchset and history) and bdl-2 (entry.search only in searchset).
transaction
A transaction is the right choice when entries depend on each other — creating a Patient and their Observations in one call, for example.
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:61ebe359-bfdc-4613-8bf2-c5e300945f0a",
"resource": {
"resourceType": "Patient",
"identifier": [{ "system": "http://hospital.example.org/mrn", "value": "00123456" }],
"name": [{ "family": "Shaw", "given": ["Amy"] }]
},
"request": {
"method": "POST",
"url": "Patient",
"ifNoneExist": "identifier=http://hospital.example.org/mrn|00123456"
}
},
{
"fullUrl": "urn:uuid:88f151c0-a954-468a-88bd-5ae15c08e059",
"resource": {
"resourceType": "Observation",
"status": "final",
"code": { "coding": [{ "system": "http://loinc.org", "code": "29463-7", "display": "Body weight" }] },
"subject": { "reference": "urn:uuid:61ebe359-bfdc-4613-8bf2-c5e300945f0a" },
"valueQuantity": { "value": 68.5, "unit": "kg", "system": "http://unitsofmeasure.org", "code": "kg" }
},
"request": { "method": "POST", "url": "Observation" }
}
]
}
What the server does:
- Processes entries in a fixed order regardless of their position in the Bundle: DELETE, then POST, then PUT/PATCH, then GET/HEAD.
- Assigns ids to created resources and rewrites every
urn:uuidreference to the newPatient/{id}. - If any entry fails, rolls back everything and returns an error (usually an OperationOutcome) instead of a transaction-response.
ifNoneExist makes the Patient create conditional: if a patient with that MRN already exists, the server uses it instead of creating a duplicate. That's the standard way to make a load idempotent, so re-running it doesn't duplicate patients.
batch
A batch looks the same, but each entry is processed on its own. One entry failing doesn't affect the others, and the response reports a status per entry.
The catch: entries in a batch must not depend on each other. A urn:uuid reference from one batch entry to another isn't resolved. Use a batch for independent work — fetching twenty unrelated resources in one round trip, or bulk-updating records that don't reference each other.
{
"resourceType": "Bundle",
"type": "batch",
"entry": [
{ "request": { "method": "GET", "url": "Patient/123" } },
{ "request": { "method": "GET", "url": "Observation?patient=123&_count=5&_sort=-date" } },
{ "request": { "method": "DELETE", "url": "Flag/old-flag-1" } }
]
}
transaction-response and batch-response
The server answers with one response entry per request entry, in the same order:
{
"resourceType": "Bundle",
"type": "batch-response",
"entry": [
{ "resource": { "resourceType": "Patient", "id": "123" }, "response": { "status": "200 OK" } },
{ "resource": { "resourceType": "Bundle", "type": "searchset" }, "response": { "status": "200 OK" } },
{ "response": { "status": "404 Not Found", "outcome": { "resourceType": "OperationOutcome", "issue": [{ "severity": "error", "code": "not-found" }] } } }
]
}
For creates, response.location holds the new resource's URL (for example Patient/9876/_history/1). That's how you map your urn:uuid placeholders to real ids afterwards.
searchset
Returned by every search. Key parts:
total— number of matches, which may be omitted or estimated unless you ask for_total=accurate.link—self,next,previous. Follownextto page.entry.search.mode—matchfor results,includefor resources added by_include/_revinclude,outcomefor an OperationOutcome with warnings.
history
Returned by _history interactions. Each entry carries the version of the resource plus request and response, so you can tell creates, updates and deletes apart. A delete has a request with method: DELETE and no resource.
This is the one Bundle type where several entries can share a fullUrl, because each one is a different version of the same resource. Elsewhere, bdl-7 requires fullUrl to be unique unless the entries differ in meta.versionId.
document
A FHIR document is the FHIR equivalent of a signed clinical document: discharge summaries, the International Patient Summary, referral letters.
- The first entry must be a Composition, and everything it references must be in the Bundle.
Bundle.identifierandBundle.timestampare required (bdl-9, bdl-10).- Once assembled, a document is immutable. Corrections are new documents that replace the old one.
message
Used for FHIR messaging, which few REST APIs implement. The first entry is a MessageHeader that says what event the message represents and where it should go. If you're building a REST integration you almost certainly want a transaction instead.
collection
No processing rules: a bag of resources. It's what you should use for exports, test fixtures, examples and any Bundle you're not asking a server to act on. Posting a collection to a server's base URL is a frequent mistake. Servers reject it, because only transactions and batches can be processed there.
fullUrl rules
- Must be an absolute URL (
https://fhir.example.org/r4/Patient/123) or a URN (urn:uuid:...,urn:oid:...). A barePatient/123isn't allowed. - If it's a RESTful URL, it should end in
{ResourceType}/{id}matching the entry's resource. - In transactions, use
urn:uuidfor anything you're creating.
Mistakes that validators catch most often
- Missing
requeston transaction or batch entries, orrequestleft on a collection. totalon a collection — copied from a searchset response.- Duplicate
fullUrlafter merging two exports. - A document whose first entry isn't a Composition.
- Relative
fullUrlvalues likePatient/1. - Batch entries that reference each other and fail with "resource not found".
Try it
Assemble a Bundle of any type in the Bundle Builder. It generates urn:uuid fullUrls and adds request elements for transactions and batches. Then run it through the FHIR Validator. It checks the Bundle type, missing request and response elements, total and search used in the wrong Bundle type, and duplicate fullUrl values. It doesn't yet check document- or message-specific rules such as the Composition-first requirement. Both tools run in your browser.
Standards and references
- FHIR R4: Bundle (types and invariants bdl-1 to bdl-10)
- FHIR R4: RESTful API — batch and transaction
- FHIR R5 specification (subscription-notification)
FHIR Toolbox is a free collection of HL7 FHIR tools by Omindra Labs. The tools process your data in your browser; it is not uploaded for normal tool operations.