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-08-01T10:00:00Z",
    "vocab_release": "2026.2"
  }
}

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-08-01T10:00:00Z",
    "vocab_release": "2026.2"
  }
}

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"]))

Response Fields

boolean

Whether resolution completed.

object

CodeableConcept resolution.

object

Normalized coding, text, and resource_type input.

object | null

Winning input and its resolution.

object

Normalized selected input. Coding-based matches contain the selected Coding; a text-fallback match instead contains the submitted text as display and may have no system or code.

object

Resolved vocabulary, source/standard concepts, mapping method, target table, and alignment.

array

Other successful input/resolution pairs.

object

Alternative coding input.

object

Alternative resolution.

array

Codings that could not be resolved, with errors.

object

Request metadata.

string

Request correlation ID.

string

Response timestamp.

string

Vocabulary release used.

{
  "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-08-01T10:00:00Z",
    "vocab_release": "2026.2"
  }
}

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`

Each successful best_match or alternatives entry uses the same resolution shape as single resolve. When optional quality or recommendation enrichment cannot be produced, that entry remains successful and its resolution.enrichment_status identifies the unavailable enrichment. Check partial and unavailable_enrichments instead of interpreting a missing quality field or an empty recommendation list as an operational failure.

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 Fields

Response Shape

Text fallback

Errors

See also

​Overview

​Request Body

​Response Fields

​Response Shape

​Text fallback

​Errors

​See also

Overview

Request Body

Response Fields

Response Shape

Text fallback

Errors

See also