Skip to main content

​
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

​
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.
​
string
The code value from the FHIR Coding. Required when system or vocabulary_id is provided.
​
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.
​
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.
​
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, Encounter, Patient.
​
boolean
default:"false"
Include Phoebe-recommended related concepts in the response.
​
integer
default:"5"
Maximum Phoebe recommendations to return (1–20).
​
boolean
default:"false"
Include a mapping_quality signal (high, medium, low, or manual_review) on the resolution.
​
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.

​
Response Fields

​
boolean
Whether resolution completed.
​
object
Resolution result.
​
object
Normalized input (system, code, optional display/vocabulary, and resource_type).
​
object | null
Resolved concept chain, or null when no match is found.
​
string
Resolved source vocabulary.
​
object
Source concept identity and classification fields.
​
object
Mapped standard concept. For an unmapped source returned with on_unmapped=sentinel, this is a sentinel object whose concept_id is 0.
​
string
Resolution method.
​
string | null
OMOP mapping relationship when applicable.
​
string
Target OMOP CDM table.
​
string
FHIR resource/domain alignment.
​
string | null
Quality signal (high, medium, low, or manual_review), present when include_quality=true and enrichment succeeds.
​
array
Optional recommended concepts.
​
string | null
Advisory mapping note.
​
object
Request metadata.
​
string
Request correlation ID.
​
string
Response timestamp.
​
string
Vocabulary release used.

​
Response Fields

​
resolution

​
Optional-enrichment partial success

Quality validation and Phoebe recommendations do not block the core concept resolution. When either enrichment is requested, enrichment_status is included:
partial: true means the resolution succeeded but the named optional enrichments were unavailable. The affected mapping_quality or recommendations field is omitted, and no internal failure details are exposed. This distinguishes an operational quality-validation failure from a genuine mapping_quality: "manual_review", and a recommendation failure from a successful recommendations: [] result. Successful enrichment reports partial: false with an empty unavailable_enrichments array.

​
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

​
See also