Resolve FHIR Coding - OMOPHub.com API

Overview

Translate a single FHIR Coding (system URI + code) into a fully resolved OMOP concept chain: source concept, standard concept, target CDM table, optional mapping quality signal, and optional Phoebe recommendations. The resolver chains existing OMOPHub primitives - get_concept_by_code, mappings, semantic_search, validate, and recommended - behind a single composite call. If the structured code lookup fails (or only display text is provided), the resolver falls back to semantic search. Use this endpoint when you are building a FHIR-to-OMOP ETL pipeline and need to determine which OMOP CDM table a FHIR resource should land in based on its coded fields.

Resolution follows the HL7 FHIR-to-OMOP Implementation Guide (Informative 1, v1.0.0): the OMOP concept’s domain_id determines the target table (resource type is advisory), non-standard codes are standardized via Maps to, and FHIR administrative codes (gender, encounter class, condition status, …) resolve through the IG’s administrative ConceptMaps.

Request Body

system

string

FHIR code system URI, e.g. http://snomed.info/sct, http://loinc.org, or http://hl7.org/fhir/sid/icd-10-cm. Required unless vocabulary_id or display is provided.

code

string

The code value from the FHIR Coding. Required when system or vocabulary_id is provided.

display

string

Optional human-readable display text from the FHIR Coding. Used as the semantic search fallback when structured lookup fails, or as the primary input for text-only CodeableConcept resolution.

vocabulary_id

string

Direct OMOP vocabulary_id (e.g. SNOMED, ICD10CM). Alternative to system for callers who already know the OMOP vocabulary and want to skip URI resolution.

resource_type

string

FHIR resource type that carried this coding (e.g. Condition, Observation, MedicationStatement). Used to validate domain alignment and to filter the semantic search fallback. Supported values: Condition, Observation, MedicationStatement, MedicationRequest, MedicationAdministration, Immunization, Procedure, AllergyIntolerance, DiagnosticReport.

include_recommendations

boolean

default:"false"

Include Phoebe-recommended related concepts in the response.

recommendations_limit

integer

default:"5"

Maximum Phoebe recommendations to return (1–20).

include_quality

boolean

default:"false"

Include a mapping_quality signal (high, medium, low, or manual_review) on the resolution.

on_unmapped

string

default:"error"

Behavior when no concept can be located at all. error (default) returns a 404 concept_not_found. sentinel instead returns a resolution with the OMOP concept_id 0 sentinel so ETL pipelines always get a writable row. (A concept that resolves but has no standard Maps to target always returns standard_concept.concept_id = 0 regardless of this flag.)

At least one of (system + code), (vocabulary_id + code), or display must be provided.

curl -X POST "https://api.omophub.com/v1/fhir/resolve" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system": "http://snomed.info/sct",
    "code": "44054006",
    "resource_type": "Condition"
  }'

{
  "success": true,
  "data": {
    "input": {
      "system": "http://snomed.info/sct",
      "code": "44054006",
      "resource_type": "Condition"
    },
    "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": "aligned"
    }
  },
  "meta": {
    "request_id": "req_fhir_resolve_123",
    "timestamp": "2026-04-09T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

Response Fields

`resolution`

Field	Type	Description
`vocabulary_id`	string \| null	OMOP vocabulary the source concept came from
`source_concept`	object	The concept resolved from the input code
`standard_concept`	object	The standard concept (after any `Maps to` traversal)
`value_as_concept`	object	Present only for composite concepts decomposed via `Maps to value` (e.g. “Allergy to penicillin” → standard “Allergy to drug” + value “Penicillin G”). HL7 FHIR-to-OMOP IG Value-as-Concept pattern.
`value_target_field`	string	OMOP field the value concept populates (e.g. `value_as_concept_id`). Present with `value_as_concept`.
`mapping_type`	string	`direct`, `mapped`, `semantic_match`, or `unmapped`
`relationship_id`	string	`Maps to` for non-standard traversal, or the IG ConceptMap relationship for administrative codes
`similarity_score`	number	Only for `semantic_match` - cosine similarity (0–1)
`target_table`	string \| null	OMOP CDM target table (e.g. `condition_occurrence`, or `person` for demographic domains — the specific column is given by the concept’s `domain_id`)
`domain_resource_alignment`	string	`aligned`, `misaligned`, or `not_checked`
`alignment_note`	string	Human-readable explanation when misaligned
`mapping_quality`	string	Only when `include_quality=true`: `high`, `medium`, `low`, or `manual_review`
`quality_note`	string	Advisory note, e.g. for semantic matches
`alternative_standard_concepts`	array	Additional `Maps to` targets when the source maps to several standard concepts
`recommendations`	array	Phoebe recommendations when `include_recommendations=true`
`concept_map_id`	string	Set when an administrative code resolved via an IG ConceptMap (e.g. `GenderClass`). See Administrative ConceptMaps.
`mapping_note`	string	Advisory note for ConceptMap resolution (broader/narrower relationship, cross-map ambiguity, or IG-declared unmapped code)

Mapping types

direct - The source code was found by exact lookup and is itself a standard concept.
mapped - The source code was found but is non-standard; the response contains the standard target reached via Maps to.
semantic_match - The resolver fell back to semantic search (code miss or text-only input). Similarity score ≥ 0.70 is required for a match; ≥ 0.85 is flagged as high quality, 0.70–0.84 as medium.
unmapped - The source concept was found but has no standard target via Maps to (or nothing resolved at all and on_unmapped=sentinel). Per OMOP / the FHIR-to-OMOP IG, standard_concept.concept_id is the 0 sentinel (“No matching concept”) and target_table is null; the real source concept (when one was found) is preserved in source_concept. Review recommended.

Errors

HTTP	`error.code`	Cause
400	`unknown_system`	Unknown FHIR code system URI. Response includes a `suggestion` when a close match exists.
400	`missing_input`	None of `(system + code)`, `(vocabulary_id + code)`, or `display` was provided.
400	`invalid_resource_type`	`resource_type` is not a supported FHIR resource type.
403	`vocabulary_restricted`	The code system maps to a restricted vocabulary.
404	`concept_not_found`	No concept was found via direct lookup and no semantic fallback candidate met the 0.70 threshold. Pass `on_unmapped=sentinel` to receive a `concept_id` 0 record instead of this error.

Documentation Index

​Overview

​Request Body

​Response Fields

​resolution

​Mapping types

​Errors

​See also

Overview

Request Body

Response Fields

`resolution`

Mapping types

Errors

See also