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

typeWho creates itMeaningentry.requestentry.response
documentClientA signed, persistent clinical document; first entry is a Compositionnot allowednot allowed
messageClientA message for messaging workflows; first entry is a MessageHeadernot allowednot allowed
transactionClientApply all entries atomically — all succeed or none dorequirednot allowed
transaction-responseServerOutcome of a transactionnot allowedrequired
batchClientApply each entry independentlyrequirednot allowed
batch-responseServerPer-entry outcomes of a batchnot allowedrequired
searchsetServerResults of a searchnot allowednot allowed
historyServerVersions of resources over timerequiredrequired
collectionAnyoneA set of resources with no processing rulesnot allowednot allowed
subscription-notificationServerA notification for a topic-based subscription (R5 only)not allowednot 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:

  1. Processes entries in a fixed order regardless of their position in the Bundle: DELETE, then POST, then PUT/PATCH, then GET/HEAD.
  2. Assigns ids to created resources and rewrites every urn:uuid reference to the new Patient/{id}.
  3. 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. Follow next to page.
  • entry.search.mode — match for results, include for resources added by _include/_revinclude, outcome for 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.identifier and Bundle.timestamp are 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 bare Patient/123 isn't allowed.
  • If it's a RESTful URL, it should end in {ResourceType}/{id} matching the entry's resource.
  • In transactions, use urn:uuid for anything you're creating.

Mistakes that validators catch most often

  1. Missing request on transaction or batch entries, or request left on a collection.
  2. total on a collection — copied from a searchset response.
  3. Duplicate fullUrl after merging two exports.
  4. A document whose first entry isn't a Composition.
  5. Relative fullUrl values like Patient/1.
  6. 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 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.