Skip to main content

​
Overview

Batch-resolve up to 100 FHIR Coding inputs in a single request. The batch never fails because one coding could not be resolved - failing items are reported inline in the results array with an error field, and the surrounding successful resolutions are still returned. Use this endpoint in ETL pipelines where you are iterating over a FHIR Bundle or exporting a FHIR dataset and need high-throughput code resolution.

​
Request Body

​
codings
array
required
Array of FHIR coding inputs. Each item accepts the same fields as the single resolve endpoint: system, code, display, vocabulary_id. Maximum 100 items.
​
resource_type
string
FHIR resource type applied to every item in the batch. Used for domain alignment checks and as the domain filter on semantic search fallbacks. Supported values match the single resolve endpoint.
​
include_recommendations
boolean
default:"false"
Include Phoebe recommendations on every successful resolution.
​
recommendations_limit
integer
default:"5"
Maximum Phoebe recommendations per resolved concept (1–20).
​
include_quality
boolean
default:"false"
Include a mapping_quality signal on every successful resolution.
curl -X POST "https://api.omophub.com/v1/fhir/resolve/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "codings": [
      { "system": "http://snomed.info/sct", "code": "44054006" },
      { "system": "http://loinc.org", "code": "2951-2" },
      { "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "197696" },
      { "system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E11.9" }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "input": {
          "system": "http://snomed.info/sct",
          "code": "44054006"
        },
        "resolution": {
          "vocabulary_id": "SNOMED",
          "source_concept": {
            "concept_id": 201826,
            "concept_name": "Type 2 diabetes mellitus",
            "concept_code": "44054006",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S"
          },
          "standard_concept": {
            "concept_id": 201826,
            "concept_name": "Type 2 diabetes mellitus",
            "concept_code": "44054006",
            "vocabulary_id": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S"
          },
          "mapping_type": "direct",
          "target_table": "condition_occurrence",
          "domain_resource_alignment": "not_checked"
        }
      },
      {
        "input": {
          "system": "http://snomed.info/sct",
          "code": "00000000"
        },
        "error": {
          "code": "concept_not_found",
          "message": "No matching OMOP concept found for the provided input",
          "details": {
            "vocabulary_id": "SNOMED",
            "code": "00000000"
          }
        }
      }
    ],
    "summary": {
      "total": 2,
      "resolved": 1,
      "failed": 1
    }
  },
  "meta": {
    "request_id": "req_fhir_batch_123",
    "timestamp": "2026-04-09T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

​
Response Shape

Each entry in results is either a successful resolution (same shape as POST /fhir/resolve) or an error entry: 
{
  "input": { /* echoed coding plus resource_type */ },
  "error": {
    "code": "concept_not_found",
    "message": "…",
    "details": { /* optional */ }
  }
}
The summary block reports totals to make monitoring easier:
FieldTypeDescription
totalintegerNumber of codings submitted
resolvedintegerNumber that resolved successfully
failedintegerNumber that reported an inline error

​
Errors

HTTPerror.codeCause
400validation_errorcodings missing, empty, or exceeds 100 items
400invalid_resource_typeresource_type is not a supported FHIR resource type
Per-item errors (e.g. concept_not_found, unknown_system, vocabulary_restricted) are returned inline in the results array and do not fail the batch.

​
See also