Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.omophub.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

A FHIR CodeableConcept often contains multiple Coding entries for the same clinical idea - for example, both a SNOMED code and an ICD-10-CM code for the same condition. This endpoint resolves every coding in parallel and picks the best match according to OHDSI vocabulary preference:
  1. SNOMED CT - conditions, procedures, observations
  2. RxNorm - drugs
  3. LOINC - measurements
  4. CVX - vaccines
  5. ICD-10 / ICD-10-CM - classification
  6. Other vocabularies
The remaining resolutions are returned in alternatives, and any codings that failed to resolve are reported in unresolved. If no coding resolves and a top-level text is provided, the resolver falls back to semantic search on that text.

​
Request Body

​
coding
array
Array of FHIR Coding objects, each with required system and code fields, an optional display, and an optional user_selected boolean. Maximum 20 codings per request. When a coding sets user_selected: true it wins best_match over vocabulary preference (FHIR-to-OMOP IG CodeableConcept pattern, mirroring FHIR Coding.userSelected).
​
text
string
Optional top-level CodeableConcept.text. Used as the semantic search fallback when none of the structured codings can be resolved.
​
resource_type
string
FHIR resource type carrying the CodeableConcept. Applied to every resolution for domain alignment and semantic search filtering.
​
include_recommendations
boolean
default:"false"
Include Phoebe recommendations on resolved concepts.
​
recommendations_limit
integer
default:"5"
Maximum Phoebe recommendations per resolved concept (1–20).
​
include_quality
boolean
default:"false"
Include a mapping_quality signal on resolved concepts.
At least one of coding or text must be provided. 
curl -X POST "https://api.omophub.com/v1/fhir/resolve/codeable-concept" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "44054006",
        "display": "Type 2 diabetes mellitus"
      },
      {
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "code": "E11.9",
        "display": "Type 2 diabetes mellitus without complications"
      }
    ],
    "resource_type": "Condition"
  }'

{
  "success": true,
  "data": {
    "input": {
      "coding": [
        { "system": "http://snomed.info/sct", "code": "44054006" },
        { "system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E11.9" }
      ],
      "resource_type": "Condition"
    },
    "best_match": {
      "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"
      }
    },
    "alternatives": [
      {
        "input": {
          "system": "http://hl7.org/fhir/sid/icd-10-cm",
          "code": "E11.9",
          "resource_type": "Condition"
        },
        "resolution": {
          "vocabulary_id": "ICD10CM",
          "source_concept": {
            "concept_id": 45576876,
            "concept_name": "Type 2 diabetes mellitus without complications",
            "concept_code": "E11.9",
            "vocabulary_id": "ICD10CM",
            "domain_id": "Condition",
            "concept_class_id": "5-char billing code",
            "standard_concept": null
          },
          "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": "mapped",
          "relationship_id": "Maps to",
          "target_table": "condition_occurrence",
          "domain_resource_alignment": "aligned"
        }
      }
    ],
    "unresolved": []
  },
  "meta": {
    "request_id": "req_fhir_cc_123",
    "timestamp": "2026-04-09T10:00:00Z",
    "vocab_release": "2026.1"
  }
}

​
Response Shape

FieldTypeDescription
inputobjectEcho of the submitted CodeableConcept
best_matchobject | nullHighest-priority successful resolution, or null if none resolved
alternativesarrayOther successful resolutions, ordered by vocabulary preference
unresolvedarrayCodings that failed, each with input and error

​
Text fallback

When every structured coding entry fails to resolve and the request includes a non-empty text, the resolver performs a semantic search against text and returns the top match as best_match. The failed structured codings are still reported in unresolved so you can audit why they didn’t resolve.

​
Errors

HTTPerror.codeCause
400validation_errorNeither coding nor text provided, or coding exceeds 20 items
400invalid_resource_typeresource_type is not a supported FHIR resource type
Per-coding errors are reported inline in unresolved.

​
See also