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

# Resolve FHIR CodeableConcept

## 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

<ParamField body="coding" type="array">
  Array of FHIR `Coding` objects, each with required `system` and `code`
  fields and an optional `display`. Maximum 20 codings per request.
</ParamField>

<ParamField body="text" type="string">
  Optional top-level `CodeableConcept.text`. Used as the semantic search
  fallback when none of the structured codings can be resolved.
</ParamField>

<ParamField body="resource_type" type="string">
  FHIR resource type carrying the CodeableConcept. Applied to every
  resolution for domain alignment and semantic search filtering.
</ParamField>

<ParamField body="include_recommendations" type="boolean" default="false">
  Include Phoebe recommendations on resolved concepts.
</ParamField>

<ParamField body="recommendations_limit" type="integer" default="5">
  Maximum Phoebe recommendations per resolved concept (1–20).
</ParamField>

<ParamField body="include_quality" type="boolean" default="false">
  Include a `mapping_quality` signal on resolved concepts.
</ParamField>

At least one of `coding` or `text` must be provided.

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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"]))
  ```
</RequestExample>

<ResponseExample>
  ```json SNOMED wins over ICD-10-CM theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## 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`.

## See also

* [Single resolve](/api-reference/fhir/resolve)
* [Batch resolve](/api-reference/fhir/resolve-batch)
* [FHIR Integration Guide](/guides/integration/fhir-integration)