Skip to main content

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.

​
Get Mappings for a Concept

Find how a concept maps to other vocabularies: 
const { data, error } = await client.mappings.get(201826); // Type 2 diabetes mellitus
if (error) throw new Error(error.message);

for (const mapping of data.mappings) {
  console.log(`${mapping.relationship_id}: ${mapping.target_concept_name}`);
}

​
Filter by Target Vocabulary

const { data } = await client.mappings.get(201826, {
  targetVocabulary: 'ICD10CM',
});

for (const mapping of data?.mappings ?? []) {
  console.log(`${mapping.target_concept_id}: ${mapping.target_concept_name}`);
}

​
Include Invalid Mappings

await client.mappings.get(201826, {
  targetVocabulary: 'ICD10CM',
  includeInvalid: true,
});

​
Use Specific Vocabulary Version

await client.mappings.get(201826, {
  targetVocabulary: 'ICD10CM',
  vocabRelease: '2025.1',
});

​
Map Multiple Concepts

Map a batch of concept IDs to a target vocabulary: 
const { data } = await client.mappings.map({
  targetVocabulary: 'ICD10CM',
  sourceConcepts: [201826, 4329847], // Diabetes, MI
});

for (const mapping of data?.mappings ?? []) {
  console.log(`${mapping.source_concept_id} → ${mapping.target_concept_id}`);
}

​
Map Using Vocabulary Codes

Map concepts directly using vocabulary codes instead of OMOP concept IDs: 
const { data } = await client.mappings.map({
  targetVocabulary: 'RxNorm',
  sourceCodes: [
    { vocabulary_id: 'SNOMED', concept_code: '387517004' }, // Acetaminophen
    { vocabulary_id: 'SNOMED', concept_code: '108774000' }, // Anastrozole
  ],
});

for (const mapping of data?.mappings ?? []) {
  console.log(`${mapping.source_concept_name} → ${mapping.target_concept_name}`);
}
Use sourceCodes when you have vocabulary-specific codes (e.g. SNOMED codes from your source system). Use sourceConcepts when you already have OMOP concept IDs. You cannot use both in the same request - the SDK enforces this at the type level via a discriminated union and re-validates at runtime so JS callers also get a structured missing_required_field error rather than a wire 400.

​
Map with Specific Mapping Type

Filter mappings by type: 
await client.mappings.map({
  targetVocabulary: 'ICD10CM',
  sourceConcepts: [201826, 192671],
  mappingType: 'direct', // 'direct' | 'equivalent' | 'broader' | 'narrower'
});

​
Vocabulary Release Pinning

vocabRelease is sent as a query-string parameter, not in the JSON body - matches the Python SDK convention: 
await client.mappings.map({
  targetVocabulary: 'SNOMED',
  sourceConcepts: [201826],
  vocabRelease: '2025.1',
});
// → POST /concepts/map?vocab_release=2025.1

​
Procedure-Domain Vocabulary Priority

For Procedure-domain sources, the API applies a fallback vocabulary priority when targetVocabulary is left to “best fit” semantics: 
SNOMED → LOINC → CPT4 → HCPCS → ICD10PCS → ICD9Proc → OPCS4 → OMOP Extension

​
Common Use Case: SNOMED → ICD-10

Option 1: Direct mapping using vocabulary codes (recommended) 
const { data } = await client.mappings.map({
  targetVocabulary: 'ICD10CM',
  sourceCodes: [
    { vocabulary_id: 'SNOMED', concept_code: '44054006' }, // Type 2 diabetes
  ],
});

for (const m of data?.mappings ?? []) {
  console.log(`  → ${m.target_concept_name} (${m.target_concept_code})`);
}
Option 2: Using OMOP concept IDs 
// First resolve the OMOP concept ID
const lookup = await client.concepts.getByCode('SNOMED', '44054006');
if (lookup.error || !lookup.data) throw new Error('Concept not found');

// Then map using the concept ID
const { data } = await client.mappings.get(lookup.data.concept_id, {
  targetVocabulary: 'ICD10CM',
});

console.log(`Mappings for ${lookup.data.concept_name}:`);
for (const m of data?.mappings ?? []) {
  console.log(`  → ${m.target_concept_name}`);
}

​
Idempotency

POST endpoints (mappings.map) only retry on transient failures when an Idempotency-Key is provided: 
await client.mappings.map({
  targetVocabulary: 'SNOMED',
  sourceConcepts: [201826],
  idempotencyKey: 'my-pipeline-run-2026-05-30-batch-1',
});

​
Parameters

ParameterTypeDefaultDescription
targetVocabularystringrequiredTarget vocabulary ID (e.g. 'SNOMED', 'RxNorm')
sourceConceptsnumber[]XOR with sourceCodesOMOP concept IDs to map
sourceCodes{ vocabulary_id, concept_code }[]XOR with sourceConceptsNative vocabulary codes
mappingType'direct' | 'equivalent' | 'broader' | 'narrower'-Filter mappings by type
includeInvalidbooleanfalseInclude deprecated mappings
vocabReleasestring-Pin to a vocabulary release (sent as query param)
idempotencyKeystring-Per-call Idempotency-Key header (enables retry on 5xx)