Skip to main content

​
Overview

This endpoint maps medical concepts from source vocabularies to target vocabularies, finding equivalent or related concepts across different medical terminology systems. It’s essential for healthcare data integration, cross-system interoperability, and clinical data standardization.

​
Request Body

​
Query Parameters

​
string
Specific vocabulary release version to use for mapping (e.g., “2025.1”, “2024.2”). When not specified, uses the default/latest vocabulary version.

​
Response

​
boolean
Indicates if the request was successful
​
object
Error information (present only on error responses)
​
object
Contains the concept mapping results
​
object
Response metadata

​
Sources That Produce No Mappings

Every source you submit is accounted for. A source either appears as the source_concept_id of at least one entry in mappings, or it appears in unmapped_sources with a reason:
The two reasons mean different things and should be handled differently:
  • source_not_found - the code or concept ID does not exist in this vocabulary release. Usually a data-quality problem on your side: a typo, the wrong vocabulary_id, or a code that was retired before the release you are querying.
  • no_mapping_found - the source exists, but OMOP has no mapping from it to target_vocabulary. Often correct and expected: mappings run from non-standard concepts to standard ones, so a SNOMED source frequently has no mapping to ICD-10-CM (see below).

​
Duplicate inputs

Sources are accounted for per submitted entry, not per distinct concept. Sending the same code twice gives requested_sources: 2 and mapped_sources: 2, so mapped_sources + unmapped_sources == requested_sources always holds and you can line the counts up against what you sent. mappings is not duplicated to match - the database is asked about each distinct concept once - so total_mappings may be lower than mapped_sources. total_mappings is always the length of the mappings array.

​
Restricted vocabularies

Licensed vocabularies (CPT4, GPI, MedDRA) are not reported through unmapped_sources, and the two input styles differ:
  • source_codes naming a restricted vocabulary_id fails the whole request with HTTP 403 vocabulary_restricted, matching GET /v1/search/concepts. Because you named the vocabulary, refusing outright reveals nothing you did not already state.
  • source_concepts carrying the ID of a restricted concept is reported as source_not_found, deliberately. An OMOP concept ID does not say which vocabulary it belongs to, so a 403 here would confirm that the concept exists and is licensed - which is exactly what the restriction is meant to withhold.
target_vocabulary is checked first: naming a restricted vocabulary there is always a 403, whichever input style you use. A request in which nothing resolved still returns HTTP 200 - the status code does not change with the proportion of sources that resolved, so a partial result and a total miss have the same shape and one parsing path. Check summary.mapped_sources rather than inferring failure from an empty mappings array.
unmapped_sources and summary were added on 2026-09-05. Before that, a code that did not exist was silently dropped from the request and the response was indistinguishable from one whose concepts genuinely had no mappings.

​
Understanding OMOP Mapping Direction

In OMOP, mappings go from non-standard concepts TO standard concepts. This means:
  • ICD-10-CM → SNOMED works (ICD-10 is non-standard, SNOMED is standard)
  • SNOMED → ICD-10-CM often returns empty (SNOMED concepts are already standard - they are mapping targets, not sources)
If you get empty results, check whether your source concept is already a standard concept. Use GET /v1/concepts/{id} to check the standard_concept field - if it’s "S", try mapping in the opposite direction.

​
Usage Examples

​
ICD-10 to SNOMED (most common use case)

Map ICD-10-CM diagnosis codes to SNOMED standard concepts:

​
Cross-System Integration

Map multiple ICD-10 codes for EHR standardization:

​
Drug Mapping

Map drug codes from NDC to RxNorm:

​
Using OMOP Concept IDs

If you already have OMOP concept IDs (e.g., from a search result), use source_concepts instead of source_codes:
The source_concepts parameter expects OMOP concept IDs (internal database IDs), NOT vocabulary-specific codes. If you have vocabulary codes (e.g., ICD-10 code “E11.9”), use the source_codes parameter instead, or first look up the OMOP concept ID using /v1/concepts/by-code/{vocabulary}/{code}.