Skip to main content
Spec reference: https://hl7.org/fhir/bundle.html
A Bundle is FHIR’s container for grouping multiple resources together. You’ll encounter bundles in search results, batch operations, and transactions.

​
What You’ll See

Every bundle has a type and an array of entry objects: 
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 42,
  "link": [
    { "relation": "self", "url": "http://example.org/fhir/Patient?_count=10" },
    {
      "relation": "next",
      "url": "http://example.org/fhir/Patient?_count=10&_offset=10"
    }
  ],
  "entry": [
    {
      "fullUrl": "http://example.org/fhir/Patient/123",
      "resource": {
        "resourceType": "Patient",
        "id": "123",
        "name": [{ "family": "Doe" }]
      }
    }
  ]
}

​
Common Bundle Types

TypeWhen You See It
searchsetSearch results (most common)
historyResource version history
transactionAtomic multi-operation requests
batchMultiple independent operations
collectionArbitrary groupings

​
Search Results (searchset)

Search operations always return bundles: 
GET /fhir/Patient?name=Doe
Response: 
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "http://example.org/fhir/Patient/123",
      "resource": { "resourceType": "Patient", "id": "123" }
    }
  ]
}

​
Pagination

Use the link array to navigate pages: 
{
  "link": [
    { "relation": "self", "url": "..." },
    { "relation": "next", "url": "..." }
  ]
}
Follow the server-provided URLs — don’t construct your own pagination.

​
Transactions & Batch

Send multiple operations in one request. See Batch & Transaction for details.

​
References Within Bundles

When resources reference each other in a bundle, include fullUrl so references resolve correctly: 
{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:patient-1",
      "resource": { "resourceType": "Patient", "id": "patient-1" }
    },
    {
      "fullUrl": "urn:uuid:obs-1",
      "resource": {
        "resourceType": "Observation",
        "subject": { "reference": "urn:uuid:patient-1" }
      }
    }
  ]
}
Relative references (like Patient/123) also work — they’re resolved using the bundle entry’s base URL.

​
Try It

1

See a search bundle

Search operations return bundles automatically:
curl -H "Accept: application/fhir+json" \
  "http://localhost:8080/fhir/Patient?_count=3"
Notice the Bundle with type: "searchset" and entries.
2

Use bundles for transactions

See Batch & Transaction for batch and transaction examples.

​
Next Steps

Search

Search returns bundles automatically

Batch & Transaction

Batch and transaction bundles