Resolve FHIR CodeableConcept

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"
  }'

import requests

resp = requests.post(
    "https://api.omophub.com/v1/fhir/resolve/codeable-concept",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "coding": [
            {"system": "http://snomed.info/sct", "code": "44054006"},
            {"system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E11.9"},
        ],
        "resource_type": "Condition",
    },
)
data = resp.json()["data"]
print(data["best_match"]["resolution"]["standard_concept"]["concept_name"])
print("alternatives:", len(data["alternatives"]))

{
  "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"
  }
}

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:

SNOMED CT - conditions, procedures, observations
RxNorm - drugs
LOINC - measurements
CVX - vaccines
ICD-10 / ICD-10-CM - classification
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

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

string

Optional top-level CodeableConcept.text. Used as the semantic search fallback when none of the structured codings can be resolved.

string

FHIR resource type carrying the CodeableConcept. Applied to every resolution for domain alignment and semantic search filtering.

boolean

default:"false"

Include Phoebe recommendations on resolved concepts.

integer

default:"5"

Maximum Phoebe recommendations per resolved concept (1–20).

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"
  }'

import requests

resp = requests.post(
    "https://api.omophub.com/v1/fhir/resolve/codeable-concept",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "coding": [
            {"system": "http://snomed.info/sct", "code": "44054006"},
            {"system": "http://hl7.org/fhir/sid/icd-10-cm", "code": "E11.9"},
        ],
        "resource_type": "Condition",
    },
)
data = resp.json()["data"]
print(data["best_match"]["resolution"]["standard_concept"]["concept_name"])
print("alternatives:", len(data["alternatives"]))

{
  "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

Field	Type	Description
`input`	object	Echo of the submitted `CodeableConcept`
`best_match`	object \| null	Highest-priority successful resolution, or `null` if none resolved
`alternatives`	array	Other successful resolutions, ordered by vocabulary preference
`unresolved`	array	Codings 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

HTTP	`error.code`	Cause
400	`validation_error`	Neither `coding` nor `text` provided, or `coding` exceeds 20 items
400	`invalid_resource_type`	`resource_type` is not a supported FHIR resource type

Per-coding errors are reported inline in unresolved.

API Reference

Search

Concepts

Concept Hierarchy

Mappings

FHIR Resolver

Relationships

Domains & Classifications

Vocabularies

Resolve FHIR CodeableConcept

Overview

Request Body

Response Shape

Text fallback

Errors

See also

​Overview

​Request Body

​Response Shape

​Text fallback

​Errors

​See also

Overview

Request Body

Response Shape

Text fallback

Errors

See also