Skip to main content

​
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:
OperationExample URL
$lookupCodeSystem/$lookup?system=http://snomed.info/sct&code=44054006
$validate-codeCodeSystem/$validate-code?url=http://snomed.info/sct&code=44054006
$translateConceptMap/$translate?sourceCode=E11.9&system=http://hl7.org/fhir/sid/icd-10-cm&targetSystem=https://fhir-terminology.ohdsi.org
$expandValueSet/$expand?url=http://snomed.info/sct?fhir_vs=isa/73211009&count=5
$subsumesCodeSystem/$subsumes?codeA=73211009&codeB=44054006&system=http://snomed.info/sct
ValueSet $validate-codeValueSet/$validate-code?url=http://snomed.info/sct?fhir_vs&system=http://snomed.info/sct&code=44054006

​
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

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