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.

​
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.
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

FieldTypeDescription
vocabulary_idstring | nullOMOP vocabulary the source concept came from
source_conceptobjectThe concept resolved from the input code
standard_conceptobjectThe standard concept (after any Maps to traversal)
mapping_typestringdirect, mapped, semantic_match, or unmapped
relationship_idstringSet to Maps to when mapping_type = mapped
similarity_scorenumberOnly for semantic_match - cosine similarity (0–1)
target_tablestring | nullOMOP CDM target table (e.g. condition_occurrence)
domain_resource_alignmentstringaligned, misaligned, or not_checked
alignment_notestringHuman-readable explanation when misaligned
mapping_qualitystringOnly when include_quality=true: high, medium, low, or manual_review
quality_notestringAdvisory note, e.g. for semantic matches
alternative_standard_conceptsarrayAdditional Maps to targets when the source maps to several standard concepts
recommendationsarrayPhoebe recommendations when include_recommendations=true

​
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 no standard target exists via Maps to. The source is returned as-is; review recommended.

​
Errors

HTTPerror.codeCause
400unknown_systemUnknown FHIR code system URI. Response includes a suggestion when a close match exists.
400missing_inputNone of (system + code), (vocabulary_id + code), or display was provided.
400invalid_resource_typeresource_type is not a supported FHIR resource type.
403vocabulary_restrictedThe code system maps to a restricted vocabulary.
404concept_not_foundNo concept was found via direct lookup and no semantic fallback candidate met the 0.70 threshold.

​
See also