FHIR Resolver for OMOP concepts

Resolve a Single FHIR Coding

Translate a FHIR Coding (system URI + code) to an OMOP standard concept and CDM target table:

const { data, error } = await client.fhir.resolve({
  system: 'http://snomed.info/sct',
  code: '44054006',
  resourceType: 'Condition',
});
if (error) throw new Error(error.message);

const res = data.resolution;
console.log(res.standard_concept.concept_name); // "Type 2 diabetes mellitus"
console.log(res.target_table);                  // "condition_occurrence"
console.log(res.mapping_type);                  // "direct"

Resolve a Non-Standard Code (Maps-to Traversal)

ICD-10-CM and other classification codes are automatically mapped to their standard equivalents:

const { data } = await client.fhir.resolve({
  system: 'http://hl7.org/fhir/sid/icd-10-cm',
  code: 'E11.9',
});

const res = data?.resolution;
console.log(res?.source_concept.vocabulary_id);    // "ICD10CM"
console.log(res?.standard_concept.vocabulary_id);  // "SNOMED"
console.log(res?.mapping_type);                    // "mapped"
console.log(res?.target_table);                    // "condition_occurrence"

Text-Only Resolution (Semantic Search Fallback)

When no structured code is available, pass the display text for semantic search:

const { data } = await client.fhir.resolve({
  display: 'Blood Sugar',
  resourceType: 'Observation',
});

const res = data?.resolution;
console.log(res?.standard_concept.concept_name); // "Glucose [Mass/volume] in Blood"
console.log(res?.mapping_type);                  // "semantic_match"
console.log(res?.similarity_score);              // 0.91
console.log(res?.target_table);                  // "measurement"

Skip URI Resolution with vocabularyId

If you already know the OMOP vocabulary, bypass the URI lookup:

await client.fhir.resolve({
  vocabularyId: 'ICD10CM',
  code: 'E11.9',
});

Include Phoebe Recommendations

Get related concepts for phenotype development alongside the resolution:

const { data } = await client.fhir.resolve({
  system: 'http://snomed.info/sct',
  code: '44054006',
  includeRecommendations: true,
  recommendationsLimit: 5,
});

for (const rec of data?.resolution.recommendations ?? []) {
  console.log(`  ${rec.concept_name} (${rec.domain_id}) via ${rec.relationship_type}`);
}

Include Mapping Quality Signal

Assess whether a resolution needs manual review:

const { data } = await client.fhir.resolve({
  system: 'http://snomed.info/sct',
  code: '44054006',
  includeQuality: true,
});
console.log(data?.resolution.mapping_quality);
// "high", "medium", "low", or "manual_review"

Batch Resolution

Resolve up to 100 codings in a single call. Failed items are reported inline:

const { data } = await client.fhir.resolveBatch([
  { system: 'http://snomed.info/sct', code: '44054006' },
  { system: 'http://loinc.org', code: '2339-0' },
  { system: 'http://www.nlm.nih.gov/research/umls/rxnorm', code: '197696' },
]);

console.log(data?.summary); // { total: 3, resolved: 3, failed: 0 }

for (const item of data?.results ?? []) {
  const res = item.resolution;
  console.log(
    `${res.source_concept.concept_code} → ${res.standard_concept.concept_name} → ${res.target_table}`,
  );
}

Apply shared options to the entire batch:

await client.fhir.resolveBatch(
  [{ system: 'http://snomed.info/sct', code: '44054006' }],
  {
    resourceType: 'Condition',
    includeQuality: true,
  },
);

CodeableConcept Resolution

Resolve a FHIR CodeableConcept with multiple codings. Up to 20 codings per call. The resolver picks the best match per OHDSI vocabulary preference (SNOMED > RxNorm > LOINC > CVX > ICD-10):

const { data } = await client.fhir.resolveCodeableConcept(
  [
    { system: 'http://snomed.info/sct', code: '44054006' },
    { system: 'http://hl7.org/fhir/sid/icd-10-cm', code: 'E11.9' },
  ],
  { resourceType: 'Condition' },
);

const best = data?.best_match;
console.log(best?.source_concept.vocabulary_id); // "SNOMED" (preferred)
console.log(best?.target_table);                 // "condition_occurrence"

// Other resolved codings, ranked
for (const alt of data?.alternatives ?? []) {
  console.log(`  Alt: ${alt.source_concept.vocabulary_id}`);
}

// Codings that failed to resolve
for (const fail of data?.unresolved ?? []) {
  console.log(`  Failed:`, fail);
}

Falls back to the text field via semantic search when no coding resolves:

const { data } = await client.fhir.resolveCodeableConcept(
  [{ system: 'http://loinc.org', code: '99999-9' }],
  { text: 'Blood Sugar', resourceType: 'Observation' },
);
// best_match resolved via semantic search; failed coding in `unresolved`

Coding Object Form

resolve() accepts either flat fields or a nested coding object - mirrors how a FHIR library serializes a Coding:

// Nested coding form
await client.fhir.resolve({
  coding: {
    system: 'http://snomed.info/sct',
    code: '44054006',
    display: 'Type 2 diabetes',
    userSelected: true,
  },
  resourceType: 'Condition',
});

// Flat-form (equivalent)
await client.fhir.resolve({
  system: 'http://snomed.info/sct',
  code: '44054006',
  display: 'Type 2 diabetes',
  resourceType: 'Condition',
});

Flat fields override coding-object fields when both are supplied - useful for patching a single field without rebuilding the object.

// SDK input - camelCase per JS idiom
type Coding = {
  system?: string;
  code?: string;
  display?: string;
  userSelected?: boolean;   // → wire: user_selected
  vocabularyId?: string;    // → wire: vocabulary_id
};

type CodeableConcept = {
  coding?: Coding[];
  text?: string;
};

The SDK converts camelCase fields to snake_case at the wire boundary (userSelected → user_selected).

Connection Helpers

For users who want to point an external FHIR client library at OMOPHub’s FHIR Terminology Service directly, the SDK exposes a URL builder:

import { omophubFhirUrl } from '@omophub/omophub-node';

// Default R4 base URL
console.log(omophubFhirUrl());      // "https://fhir.omophub.com/fhir/r4"

// Other FHIR versions
console.log(omophubFhirUrl('r4b')); // "https://fhir.omophub.com/fhir/r4b"
console.log(omophubFhirUrl('r5'));  // "https://fhir.omophub.com/fhir/r5"
console.log(omophubFhirUrl('r6'));  // "https://fhir.omophub.com/fhir/r6"

Use the Concept Resolver (client.fhir.resolve) when you want OMOP-enriched answers - standard concept ID, CDM target table, mapping quality. Use a FHIR-native client library pointed at omophubFhirUrl() when you need raw FHIR Parameters / Bundle responses for FHIR-native tooling.

Error Handling

The resolver returns errors through the standard { data, error } shape:

const { data, error } = await client.fhir.resolve({
  system: 'http://www.ama-assn.org/go/cpt',
  code: '99213',
});

if (error) {
  console.log(error.statusCode); // 403
  console.log(error.name);       // "restricted_api_key" — canonical code (switch on this)
  console.log(error.message);    // free-form human-readable explanation
  return;
}

error.name is the stable error code listed in the table below — switch on this for programmatic handling. error.message is a free-form string from the server intended for logs and humans.

Error Code	HTTP	Cause
`unknown_system`	400	FHIR code system URI not recognised
`missing_required_field`	400 / synthetic	Neither `coding` nor `code` supplied
`not_found`	404	No concept found via lookup or semantic search
`restricted_api_key`	403	API key tier doesn’t include the requested vocabulary
`validation_error`	400 / synthetic	Batch size outside 1–100 (or 1–20 for codeableConcept)

See the FHIR Resolver API Reference for full response schemas and field descriptions.

​Resolve a Single FHIR Coding

​Resolve a Non-Standard Code (Maps-to Traversal)

​Text-Only Resolution (Semantic Search Fallback)

​Skip URI Resolution with vocabularyId

​Include Phoebe Recommendations

​Include Mapping Quality Signal

​Batch Resolution

​CodeableConcept Resolution

​Coding Object Form

​Connection Helpers

​Error Handling

Resolve a Single FHIR Coding

Resolve a Non-Standard Code (Maps-to Traversal)

Text-Only Resolution (Semantic Search Fallback)

Skip URI Resolution with vocabularyId

Include Phoebe Recommendations

Include Mapping Quality Signal

Batch Resolution

CodeableConcept Resolution

Coding Object Form

Connection Helpers

Error Handling