FHIR Batch Bundle terminology operations

Overview

Send multiple FHIR terminology operations in a single HTTP request using a FHIR Batch Bundle. Each entry is processed independently, and results are returned in a batch-response Bundle preserving entry order. This is how ETL pipelines perform bulk terminology lookups and translations efficiently via FHIR.

Request

curl -X POST "https://fhir.omophub.com/fhir/r4/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Bundle",
    "type": "batch",
    "entry": [
      {
        "request": {
          "method": "GET",
          "url": "CodeSystem/$lookup?system=http://snomed.info/sct&code=44054006"
        }
      },
      {
        "request": {
          "method": "GET",
          "url": "ConceptMap/$translate?sourceCode=E11.9&system=http://hl7.org/fhir/sid/icd-10-cm&targetSystem=https://fhir-terminology.ohdsi.org"
        }
      },
      {
        "request": {
          "method": "GET",
          "url": "CodeSystem/$validate-code?url=http://snomed.info/sct&code=44054006"
        }
      }
    ]
  }'

Response

{
  "resourceType": "Bundle",
  "type": "batch-response",
  "entry": [
    {
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          { "name": "display", "valueString": "Type 2 diabetes mellitus" }
        ]
      },
      "response": { "status": "200 OK" }
    },
    {
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          { "name": "result", "valueBoolean": true }
        ]
      },
      "response": { "status": "200 OK" }
    },
    {
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          { "name": "result", "valueBoolean": true }
        ]
      },
      "response": { "status": "200 OK" }
    }
  ]
}

Supported Operations

The following GET operations can be included in batch entries:

Operation	Example URL
`$lookup`	`CodeSystem/$lookup?system=http://snomed.info/sct&code=44054006`
`$validate-code`	`CodeSystem/$validate-code?url=http://snomed.info/sct&code=44054006`
`$translate`	`ConceptMap/$translate?sourceCode=E11.9&system=http://hl7.org/fhir/sid/icd-10-cm&targetSystem=https://fhir-terminology.ohdsi.org`
`$expand`	`ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=isa/73211009&count=5`
`$subsumes`	`CodeSystem/$subsumes?codeA=73211009&codeB=44054006&system=http://snomed.info/sct`
ValueSet `$validate-code`	`ValueSet/$validate-code?url=http://snomed.info/sct?fhir_vs&system=http://snomed.info/sct&code=44054006`

Not supported in batch. CodeSystem search, CodeSystem instance read, ValueSet search,

find-matches](/api-reference/fhir-terminology/find-matches), [

closure, and [

diff](/api-reference/fhir-terminology/diff) cannot be included in a batch Bundle - call them directly. `

find-matchesand$closure` are POST-only operations and batch only supports GET entries; the search-type and instance-read endpoints are omitted by design because they’re single-shot discovery calls that don’t benefit from batching.

Limits

Maximum 100 entries per batch. Exceeding this returns a 400 error.
GET only for MVP. POST-with-body entries are not supported.
No transaction bundles - only type: "batch" is accepted.
Metering: Each entry counts as 1 API call toward your quota.

Partial Failure

Individual entry errors do not fail the entire batch. Each entry receives its own HTTP status in the response:

{
  "resourceType": "Bundle",
  "type": "batch-response",
  "entry": [
    {
      "resource": { "resourceType": "Parameters", "parameter": [] },
      "response": { "status": "200 OK" }
    },
    {
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [{ "severity": "error", "code": "not-found", "diagnostics": "Code '999999' not found in SNOMED" }]
      },
      "response": { "status": "404 Not Found" }
    }
  ]
}

Errors

HTTP	Cause
400	Request body is not a FHIR Bundle, type is not “batch”, missing entry array, or more than 100 entries

​Overview

​Request

​Response

​Supported Operations

​Limits

​Partial Failure

​Errors