Skip to main content

​
Resolve a Single FHIR Coding

Translate a FHIR Coding (system URI + code) to an OMOP standard concept and CDM target table: 
result <- client$fhir$resolve(
  system = "http://snomed.info/sct",
  code = "44054006",
  resource_type = "Condition"
)
res <- result$resolution
cat(res$standard_concept$concept_name)  # "Type 2 diabetes mellitus"
cat(res$target_table)                    # "condition_occurrence"
cat(res$mapping_type)                    # "direct"

​
Resolve a Non-Standard Code (Maps to Traversal)

ICD-10-CM and other classification codes are automatically mapped to their standard equivalents: 
result <- client$fhir$resolve(
  system = "http://hl7.org/fhir/sid/icd-10-cm",
  code = "E11.9"
)
res <- result$resolution
cat(res$source_concept$vocabulary_id)    # "ICD10CM"
cat(res$standard_concept$vocabulary_id)  # "SNOMED"
cat(res$mapping_type)                    # "mapped"
cat(res$relationship_id)                 # "Maps to"
cat(res$target_table)                    # "condition_occurrence"

​
Text-Only Resolution (Semantic Search Fallback)

When no structured code is available, pass the display text for BioLORD semantic search: 
result <- client$fhir$resolve(
  display = "Blood Sugar",
  resource_type = "Observation"
)
res <- result$resolution
cat(res$standard_concept$concept_name)  # "Glucose [Mass/volume] in Blood"
cat(res$mapping_type)                    # "semantic_match"
cat(res$similarity_score)                # 0.91
cat(res$target_table)                    # "measurement"

​
Skip URI Resolution with vocabulary_id

If you already know the OMOP vocabulary, bypass the URI lookup: 
result <- client$fhir$resolve(
  vocabulary_id = "ICD10CM",
  code = "E11.9"
)

​
Include Phoebe Recommendations

Get related concepts for phenotype development alongside the resolution: 
result <- client$fhir$resolve(
  system = "http://snomed.info/sct",
  code = "44054006",
  include_recommendations = TRUE,
  recommendations_limit = 5L
)
for (rec in result$resolution$recommendations) {
  cat(sprintf("  %s (%s) via %s\n",
    rec$concept_name, rec$domain_id, rec$relationship_id))
}

​
Include Mapping Quality Signal

Assess whether a resolution needs manual review: 
result <- client$fhir$resolve(
  system = "http://snomed.info/sct",
  code = "44054006",
  include_quality = TRUE
)
cat(result$resolution$mapping_quality)  # "high", "medium", "low", or "manual_review"

​
Batch Resolution

Resolve up to 100 codings in a single call. Failed items are reported inline: 
result <- client$fhir$resolve_batch(list(
  list(system = "http://snomed.info/sct", code = "44054006"),
  list(system = "http://loinc.org", code = "2339-0"),
  list(system = "http://www.nlm.nih.gov/research/umls/rxnorm", code = "197696")
))

cat(sprintf("Total: %d, Resolved: %d, Failed: %d\n",
  result$summary$total, result$summary$resolved, result$summary$failed))

for (item in result$results) {
  if (!is.null(item$resolution)) {
    res <- item$resolution
    cat(sprintf("%s -> %s -> %s\n",
      res$source_concept$concept_code,
      res$standard_concept$concept_name,
      res$target_table))
  } else {
    cat(sprintf("Failed: %s - %s\n", item$error$code, item$error$message))
  }
}
Apply shared options to the entire batch: 
result <- client$fhir$resolve_batch(
  list(list(system = "http://snomed.info/sct", code = "44054006")),
  resource_type = "Condition",
  include_quality = TRUE
)

​
CodeableConcept Resolution

Resolve a FHIR CodeableConcept with multiple codings. The resolver picks the best match per OHDSI vocabulary preference (SNOMED > RxNorm > LOINC > CVX > ICD-10): 
result <- client$fhir$resolve_codeable_concept(
  coding = list(
    list(system = "http://snomed.info/sct", code = "44054006"),
    list(system = "http://hl7.org/fhir/sid/icd-10-cm", code = "E11.9")
  ),
  resource_type = "Condition"
)

best <- result$best_match$resolution
cat(best$source_concept$vocabulary_id)  # "SNOMED" (preferred)
cat(best$target_table)                   # "condition_occurrence"

# Other resolved codings ranked by preference
for (alt in result$alternatives) {
  cat(sprintf("  Alt: %s\n", alt$resolution$source_concept$vocabulary_id))
}
Falls back to the text field via semantic search when no coding resolves: 
result <- client$fhir$resolve_codeable_concept(
  coding = list(list(system = "http://loinc.org", code = "99999-9")),
  text = "Blood Sugar",
  resource_type = "Observation"
)
# best_match resolved via semantic search; failed coding in unresolved

​
Error Handling

The resolver signals errors using standard R conditions: 
tryCatch(
  client$fhir$resolve(
    system = "http://www.ama-assn.org/go/cpt",
    code = "99213"
  ),
  omophub_api_error = function(e) {
    cat(e$status_code)  # 403
    cat(e$message)       # "vocabulary_restricted"
  }
)
Error CodeHTTPCause
unknown_system400FHIR code system URI not recognized (includes a typo suggestion when close)
missing_input400Neither (system + code) / (vocabulary_id + code) / display provided
vocabulary_restricted403CPT4 excluded due to AMA licensing
concept_not_found404No concept found via lookup or semantic search
See the FHIR Resolver API Reference for full response schemas and field descriptions.