> ## 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.
Resolution follows the [HL7 FHIR-to-OMOP Implementation
Guide](https://hl7.org/fhir/uv/omop/INFORMATIVE1/en/) (Informative 1, v1.0.0):
the OMOP concept's `domain_id` determines the target table (resource type is
advisory), non-standard codes are standardized via `Maps to`, and FHIR
administrative codes (gender, encounter class, condition status, …) resolve
through the IG's [administrative
ConceptMaps](/api-reference/fhir-terminology/overview#administrative-conceptmaps).
## 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.
Behavior when no concept can be located at all. `error` (default) returns a
`404 concept_not_found`. `sentinel` instead returns a resolution with the OMOP
`concept_id` 0 sentinel so ETL pipelines always get a writable row. (A concept
that resolves but has no standard `Maps to` target always returns
`standard_concept.concept_id = 0` regardless of this flag.)
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) |
| `value_as_concept` | object | Present only for composite concepts decomposed via `Maps to value` (e.g. "Allergy to penicillin" → standard "Allergy to drug" + value "Penicillin G"). HL7 FHIR-to-OMOP IG Value-as-Concept pattern. |
| `value_target_field` | string | OMOP field the value concept populates (e.g. `value_as_concept_id`). Present with `value_as_concept`. |
| `mapping_type` | string | `direct`, `mapped`, `semantic_match`, or `unmapped` |
| `relationship_id` | string | `Maps to` for non-standard traversal, or the IG ConceptMap relationship for administrative codes |
| `similarity_score` | number | Only for `semantic_match` - cosine similarity (0–1) |
| `target_table` | string \| null | OMOP CDM target table (e.g. `condition_occurrence`, or `person` for demographic domains — the specific column is given by the concept's `domain_id`) |
| `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` |
| `concept_map_id` | string | Set when an administrative code resolved via an IG ConceptMap (e.g. `GenderClass`). See [Administrative ConceptMaps](/api-reference/fhir-terminology/overview#administrative-conceptmaps). |
| `mapping_note` | string | Advisory note for ConceptMap resolution (broader/narrower relationship, cross-map ambiguity, or IG-declared unmapped code) |
### 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 has no standard target
via `Maps to` (or nothing resolved at all and `on_unmapped=sentinel`). Per
OMOP / the FHIR-to-OMOP IG, `standard_concept.concept_id` is the `0` sentinel
("No matching concept") and `target_table` is `null`; the real source concept
(when one was found) is preserved in `source_concept`. 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. Pass `on_unmapped=sentinel` to receive a `concept_id` 0 record instead of this error. |
## 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