> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FHIR Batch Bundle terminology operations

> Execute multiple FHIR terminology operations - $lookup, $validate-code, $translate, $expand - in a single FHIR Bundle request for efficient processing.

## 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

```bash theme={null}
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

```json theme={null}
{
  "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`                          |

<Note>
  **Not supported in batch.** [CodeSystem search](/api-reference/fhir-terminology/codesystem-search), [CodeSystem instance read](/api-reference/fhir-terminology/codesystem-read), [ValueSet search](/api-reference/fhir-terminology/valueset-search), [$find-matches](/api-reference/fhir-terminology/find-matches), [$closure](/api-reference/fhir-terminology/closure), and \[$diff](/api-reference/fhir-terminology/diff) cannot be included in a batch Bundle - call them directly. `$find-matches`and`\$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.
</Note>

## 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:

```json theme={null}
{
  "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 |