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

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"])

Response Fields

boolean

Whether the batch operation completed.

object

Batch result.

array

One item per input coding, in request order.

object

Normalized coding input.

object | null

Resolved vocabulary, source/standard concepts, mapping method, target table, and alignment.

object | null

Per-item error when resolution failed.

object

Batch counts.

integer

Inputs processed.

integer

Inputs resolved.

integer

Inputs not resolved.

object

Request metadata.

string

Request correlation ID.

string

Response timestamp.

string

Vocabulary release used.

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

Optional enrichment failures do not increment failed. Each successful item has the same resolution.enrichment_status contract as single resolve, so quality validation or Phoebe recommendation degradation is reported per item while the core resolution and batch remain successful.

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 Fields

Response Shape

Errors

See also

​Overview

​Request Body

​Response Fields

​Response Shape

​Errors

​See also

Overview

Request Body

Response Fields

Response Shape

Errors

See also