> ## 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 Coding
## Overview
Translate a single FHIR `Coding` (system URI + code) into a fully resolved
OMOP concept chain: source concept, standard concept, target CDM table,
optional mapping quality signal, and optional Phoebe recommendations.
The resolver chains existing OMOPHub primitives - `get_concept_by_code`,
`mappings`, `semantic_search`, `validate`, and `recommended` - behind a
single composite call. If the structured code lookup fails (or only
`display` text is provided), the resolver falls back to semantic search.
Use this endpoint when you are building a FHIR-to-OMOP ETL pipeline and
need to determine which OMOP CDM table a FHIR resource should land in
based on its coded fields.
## Request Body
FHIR code system URI, e.g. `http://snomed.info/sct`, `http://loinc.org`,
or `http://hl7.org/fhir/sid/icd-10-cm`. Required unless `vocabulary_id`
or `display` is provided.
The code value from the FHIR `Coding`. Required when `system` or
`vocabulary_id` is provided.
Optional human-readable display text from the FHIR `Coding`. Used as the
semantic search fallback when structured lookup fails, or as the
primary input for text-only `CodeableConcept` resolution.
Direct OMOP `vocabulary_id` (e.g. `SNOMED`, `ICD10CM`). Alternative to
`system` for callers who already know the OMOP vocabulary and want to
skip URI resolution.
FHIR resource type that carried this coding (e.g. `Condition`,
`Observation`, `MedicationStatement`). Used to validate domain
alignment and to filter the semantic search fallback. Supported values:
`Condition`, `Observation`, `MedicationStatement`,
`MedicationRequest`, `MedicationAdministration`, `Immunization`,
`Procedure`, `AllergyIntolerance`, `DiagnosticReport`.
Include Phoebe-recommended related concepts in the response.
Maximum Phoebe recommendations to return (1–20).
Include a `mapping_quality` signal (`high`, `medium`, `low`, or
`manual_review`) on the resolution.
At least one of (`system` + `code`), (`vocabulary_id` + `code`), or
`display` must be provided.
```bash cURL (SNOMED direct) theme={null}
curl -X POST "https://api.omophub.com/v1/fhir/resolve" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"system": "http://snomed.info/sct",
"code": "44054006",
"resource_type": "Condition"
}'
```
```bash cURL (ICD-10-CM mapped) theme={null}
curl -X POST "https://api.omophub.com/v1/fhir/resolve" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"system": "http://hl7.org/fhir/sid/icd-10-cm",
"code": "E11.9",
"include_quality": true
}'
```
```bash cURL (text-only semantic fallback) theme={null}
curl -X POST "https://api.omophub.com/v1/fhir/resolve" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"display": "Blood Sugar",
"resource_type": "Observation"
}'
```
```bash cURL (with Phoebe recommendations) theme={null}
curl -X POST "https://api.omophub.com/v1/fhir/resolve" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"system": "http://snomed.info/sct",
"code": "44054006",
"include_recommendations": true,
"recommendations_limit": 5
}'
```
```python Python theme={null}
import requests
resp = requests.post(
"https://api.omophub.com/v1/fhir/resolve",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"system": "http://snomed.info/sct",
"code": "44054006",
"resource_type": "Condition",
},
)
data = resp.json()["data"]
print(data["resolution"]["standard_concept"]["concept_id"]) # 201826
print(data["resolution"]["target_table"]) # condition_occurrence
```
```json Direct SNOMED resolution theme={null}
{
"success": true,
"data": {
"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"
}
},
"meta": {
"request_id": "req_fhir_resolve_123",
"timestamp": "2026-04-09T10:00:00Z",
"vocab_release": "2025.2"
}
}
```
```json ICD-10-CM mapped to SNOMED theme={null}
{
"success": true,
"data": {
"input": {
"system": "http://hl7.org/fhir/sid/icd-10-cm",
"code": "E11.9"
},
"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": "not_checked",
"mapping_quality": "high"
}
}
}
```
```json Semantic search fallback theme={null}
{
"success": true,
"data": {
"input": {
"display": "Blood Sugar",
"resource_type": "Observation"
},
"resolution": {
"vocabulary_id": null,
"source_concept": {
"concept_id": 3004501,
"concept_name": "Glucose [Mass/volume] in Blood",
"concept_code": "2339-0",
"vocabulary_id": "LOINC",
"domain_id": "Measurement",
"concept_class_id": "Lab Test",
"standard_concept": "S"
},
"standard_concept": {
"concept_id": 3004501,
"concept_name": "Glucose [Mass/volume] in Blood",
"concept_code": "2339-0",
"vocabulary_id": "LOINC",
"domain_id": "Measurement",
"concept_class_id": "Lab Test",
"standard_concept": "S"
},
"mapping_type": "semantic_match",
"similarity_score": 0.91,
"target_table": "measurement",
"domain_resource_alignment": "aligned",
"quality_note": "Resolved via semantic search - verify concept match before production use"
}
}
}
```
```json With Phoebe recommendations theme={null}
{
"success": true,
"data": {
"input": {
"system": "http://snomed.info/sct",
"code": "44054006"
},
"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": "not_checked",
"recommendations": [
{
"concept_id": 4193704,
"concept_name": "Hyperglycemia",
"concept_code": "80394007",
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"relationship_id": "Has finding"
},
{
"concept_id": 4058243,
"concept_name": "Diabetic retinopathy",
"concept_code": "4855003",
"vocabulary_id": "SNOMED",
"domain_id": "Condition",
"concept_class_id": "Clinical Finding",
"standard_concept": "S",
"relationship_id": "Associated finding"
},
{
"concept_id": 3004410,
"concept_name": "Hemoglobin A1c/Hemoglobin.total in Blood",
"concept_code": "4548-4",
"vocabulary_id": "LOINC",
"domain_id": "Measurement",
"concept_class_id": "Lab Test",
"standard_concept": "S",
"relationship_id": "Has finding"
}
]
}
},
"meta": {
"request_id": "req_fhir_resolve_recs_123",
"timestamp": "2026-04-09T10:00:00Z",
"vocab_release": "2025.2"
}
}
```
## Response Fields
### `resolution`
| Field | Type | Description |
| ------------------------------- | -------------- | ------------------------------------------------------------------------------ |
| `vocabulary_id` | string \| null | OMOP vocabulary the source concept came from |
| `source_concept` | object | The concept resolved from the input code |
| `standard_concept` | object | The standard concept (after any `Maps to` traversal) |
| `mapping_type` | string | `direct`, `mapped`, `semantic_match`, or `unmapped` |
| `relationship_id` | string | Set to `Maps to` when `mapping_type = mapped` |
| `similarity_score` | number | Only for `semantic_match` - cosine similarity (0–1) |
| `target_table` | string \| null | OMOP CDM target table (e.g. `condition_occurrence`) |
| `domain_resource_alignment` | string | `aligned`, `misaligned`, or `not_checked` |
| `alignment_note` | string | Human-readable explanation when misaligned |
| `mapping_quality` | string | Only when `include_quality=true`: `high`, `medium`, `low`, or `manual_review` |
| `quality_note` | string | Advisory note, e.g. for semantic matches |
| `alternative_standard_concepts` | array | Additional `Maps to` targets when the source maps to several standard concepts |
| `recommendations` | array | Phoebe recommendations when `include_recommendations=true` |
### Mapping types
* **`direct`** - The source code was found by exact lookup and is itself a
standard concept.
* **`mapped`** - The source code was found but is non-standard; the
response contains the standard target reached via `Maps to`.
* **`semantic_match`** - The resolver fell back to semantic search
(code miss or text-only input). Similarity score ≥ 0.70 is required for
a match; ≥ 0.85 is flagged as `high` quality, 0.70–0.84 as `medium`.
* **`unmapped`** - The source concept was found but no standard target
exists via `Maps to`. The source is returned as-is; review recommended.
## Errors
| HTTP | `error.code` | Cause |
| ---- | ----------------------- | ------------------------------------------------------------------------------------------------- |
| 400 | `unknown_system` | Unknown FHIR code system URI. Response includes a `suggestion` when a close match exists. |
| 400 | `missing_input` | None of `(system + code)`, `(vocabulary_id + code)`, or `display` was provided. |
| 400 | `invalid_resource_type` | `resource_type` is not a supported FHIR resource type. |
| 403 | `vocabulary_restricted` | The code system maps to a restricted vocabulary. |
| 404 | `concept_not_found` | No concept was found via direct lookup and no semantic fallback candidate met the 0.70 threshold. |
## See also
* [Batch resolve](/api-reference/fhir/resolve-batch) - up to 100 codings per request
* [CodeableConcept resolve](/api-reference/fhir/resolve-codeable-concept) - pick the best match across multiple codings
* [FHIR Integration Guide](/guides/integration/fhir-integration) - end-to-end ETL patterns