FHIR Batch Bundle terminology operations

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({resourceType: '<string>', type: '<string>', entry: [{}]})
};

fetch('https://fhir.omophub.com/fhir/{version}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://fhir.omophub.com/fhir/{version} \
  --header 'Content-Type: application/json' \
  --data '
{
  "resourceType": "<string>",
  "type": "<string>",
  "entry": [
    {}
  ]
}
'

import requests

url = "https://fhir.omophub.com/fhir/{version}"

payload = {
    "resourceType": "<string>",
    "type": "<string>",
    "entry": [{}]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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" }
    }
  ]
}

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({resourceType: '<string>', type: '<string>', entry: [{}]})
};

fetch('https://fhir.omophub.com/fhir/{version}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://fhir.omophub.com/fhir/{version} \
  --header 'Content-Type: application/json' \
  --data '
{
  "resourceType": "<string>",
  "type": "<string>",
  "entry": [
    {}
  ]
}
'

import requests

url = "https://fhir.omophub.com/fhir/{version}"

payload = {
    "resourceType": "<string>",
    "type": "<string>",
    "entry": [{}]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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" }
    }
  ]
}

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.

Contract Parameters

string

default:"r4"

string

OMOP vocabulary release; defaults to the active release.

string

Header alternative to vocab_release; the header takes precedence.

FHIR wire version (r4, r4b, r5, or r6).

string

required

Must be Bundle.

string

required

Must be batch or transaction.

array

required

Bundle entries containing relative FHIR request method and URL.

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

Response Fields

string

Always Bundle.

string

Always batch-response.

array

One response entry per request entry, in request order.

object | null

FHIR response resource when the operation returned one.

object

Per-entry status and optional outcome.

string

FHIR HTTP status text.

object | null

OperationOutcome for an entry-level failure.

{
  "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

​Contract Parameters

​Request

​Response

​Response Fields

​Supported Operations

​Limits

​Partial Failure

​Errors

Overview

Contract Parameters

Request

Response

Response Fields

Supported Operations

Limits

Partial Failure

Errors