Resolve FHIR Codings - Batch

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

import requests

resp = requests.post(
    "https://api.omophub.com/v1/fhir/resolve/batch",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "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"},
        ],
        "include_quality": True,
    },
)
for item in resp.json()["data"]["results"]:
    if "resolution" in item:
        print(item["resolution"]["standard_concept"]["concept_name"],
              "→", item["resolution"]["target_table"])
    else:
        print("failed:", item["error"]["code"], item["input"])

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

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

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.

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.

boolean

default:"false"

Include Phoebe recommendations on every successful resolution.

integer

default:"5"

Maximum Phoebe recommendations per resolved concept (1–20).

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

import requests

resp = requests.post(
    "https://api.omophub.com/v1/fhir/resolve/batch",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "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"},
        ],
        "include_quality": True,
    },
)
for item in resp.json()["data"]["results"]:
    if "resolution" in item:
        print(item["resolution"]["standard_concept"]["concept_name"],
              "→", item["resolution"]["target_table"])
    else:
        print("failed:", item["error"]["code"], item["input"])

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

Field	Type	Description
`total`	integer	Number of codings submitted
`resolved`	integer	Number that resolved successfully
`failed`	integer	Number that reported an inline error

Errors

HTTP	`error.code`	Cause
400	`validation_error`	`codings` missing, empty, or exceeds 100 items
400	`invalid_resource_type`	`resource_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.

API Reference

Search

Concepts

Concept Hierarchy

Mappings

FHIR Resolver

Relationships

Domains & Classifications

Vocabularies

Resolve FHIR Codings - Batch

Overview

Request Body

Response Shape

Errors

See also

​Overview

​Request Body

​Response Shape

​Errors

​See also

Overview

Request Body

Response Shape

Errors

See also