Map Concepts

curl -X POST "https://api.omophub.com/v1/concepts/map" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_codes": [
      {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
      {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"}
    ],
    "target_vocabulary": "SNOMED",
    "mapping_type": "direct"
  }'

curl -X POST "https://api.omophub.com/v1/concepts/map" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_concepts": [45576876, 45591524],
    "target_vocabulary": "SNOMED",
    "mapping_type": "direct",
    "include_invalid": false
  }'

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

const client = new OMOPHub();
// Map ICD-10 codes to SNOMED. `sourceCodes` and `sourceConcepts` are XOR
// (use one or the other, never both).
const { data } = await client.mappings.map({
  sourceCodes: [
    { vocabulary_id: 'ICD10CM', concept_code: 'E11.9' },
    { vocabulary_id: 'ICD10CM', concept_code: 'I21.9' },
  ],
  targetVocabulary: 'SNOMED',
  mappingType: 'direct',
});

import requests

url = "https://api.omophub.com/v1/concepts/map"

# Map ICD-10 codes to SNOMED standard concepts
payload = {
    "source_codes": [
        {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
        {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"}
    ],
    "target_vocabulary": "SNOMED",
    "mapping_type": "direct"
}

response = requests.post(
    url,
    json=payload,
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

{
  "success": true,
  "data": {
    "mappings": [
      {
        "source_concept_id": 45576876,
        "source_concept_name": "Type 2 diabetes mellitus without complications",
        "source_concept_code": "E11.9",
        "source_vocabulary_id": "ICD10CM",
        "target_concept_id": 201826,
        "target_concept_name": "Type 2 diabetes mellitus",
        "target_concept_code": "44054006",
        "target_vocabulary_id": "SNOMED",
        "relationship_id": "Maps to",
        "relationship_name": "Maps to",
        "valid_start_date": "2023-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null,
        "mapping_confidence": 1.0,
        "mapping_type": "direct"
      },
      {
        "source_concept_id": 45591524,
        "source_concept_name": "Acute myocardial infarction, unspecified",
        "source_concept_code": "I21.9",
        "source_vocabulary_id": "ICD10CM",
        "target_concept_id": 4329847,
        "target_concept_name": "Myocardial infarction",
        "target_concept_code": "22298006",
        "target_vocabulary_id": "SNOMED",
        "relationship_id": "Maps to",
        "relationship_name": "Maps to",
        "valid_start_date": "2023-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null,
        "mapping_confidence": 1.0,
        "mapping_type": "direct"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-05T12:00:00.000Z",
    "vocab_release": "2025.1"
  }
}

curl -X POST "https://api.omophub.com/v1/concepts/map" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_codes": [
      {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
      {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"}
    ],
    "target_vocabulary": "SNOMED",
    "mapping_type": "direct"
  }'

curl -X POST "https://api.omophub.com/v1/concepts/map" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_concepts": [45576876, 45591524],
    "target_vocabulary": "SNOMED",
    "mapping_type": "direct",
    "include_invalid": false
  }'

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

const client = new OMOPHub();
// Map ICD-10 codes to SNOMED. `sourceCodes` and `sourceConcepts` are XOR
// (use one or the other, never both).
const { data } = await client.mappings.map({
  sourceCodes: [
    { vocabulary_id: 'ICD10CM', concept_code: 'E11.9' },
    { vocabulary_id: 'ICD10CM', concept_code: 'I21.9' },
  ],
  targetVocabulary: 'SNOMED',
  mappingType: 'direct',
});

import requests

url = "https://api.omophub.com/v1/concepts/map"

# Map ICD-10 codes to SNOMED standard concepts
payload = {
    "source_codes": [
        {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
        {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"}
    ],
    "target_vocabulary": "SNOMED",
    "mapping_type": "direct"
}

response = requests.post(
    url,
    json=payload,
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

{
  "success": true,
  "data": {
    "mappings": [
      {
        "source_concept_id": 45576876,
        "source_concept_name": "Type 2 diabetes mellitus without complications",
        "source_concept_code": "E11.9",
        "source_vocabulary_id": "ICD10CM",
        "target_concept_id": 201826,
        "target_concept_name": "Type 2 diabetes mellitus",
        "target_concept_code": "44054006",
        "target_vocabulary_id": "SNOMED",
        "relationship_id": "Maps to",
        "relationship_name": "Maps to",
        "valid_start_date": "2023-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null,
        "mapping_confidence": 1.0,
        "mapping_type": "direct"
      },
      {
        "source_concept_id": 45591524,
        "source_concept_name": "Acute myocardial infarction, unspecified",
        "source_concept_code": "I21.9",
        "source_vocabulary_id": "ICD10CM",
        "target_concept_id": 4329847,
        "target_concept_name": "Myocardial infarction",
        "target_concept_code": "22298006",
        "target_vocabulary_id": "SNOMED",
        "relationship_id": "Maps to",
        "relationship_name": "Maps to",
        "valid_start_date": "2023-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null,
        "mapping_confidence": 1.0,
        "mapping_type": "direct"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-05T12:00:00.000Z",
    "vocab_release": "2025.1"
  }
}

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

vocab_release

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

success

boolean

Indicates if the request was successful

error

object

Error information (present only on error responses)

Show error

code

string

Error code identifier (e.g., “INVALID_VOCABULARY”, “RATE_LIMIT_EXCEEDED”)

message

string

Human-readable error message

details

object

Additional error details including supported vocabularies and validation failures

Show details

supported_vocabularies

array

List of supported vocabulary names when vocabulary validation fails

data

object

Contains the concept mapping results

Show data

mappings

array

Array of concept mappings found

Show mappings

source_concept_id

integer

OMOP concept ID of the source concept

source_concept_name

string

Name of the source concept

source_vocabulary_id

string

Vocabulary of the source concept

target_concept_id

integer

OMOP concept ID of the mapped target concept

target_concept_name

string

Name of the target concept

target_vocabulary_id

string

Vocabulary of the target concept

target_concept_code

string

Original source code in the target vocabulary

relationship_id

string

Type of relationship between concepts

relationship_name

string

Human-readable relationship description

mapping_confidence

number

Confidence score for the mapping (0.0 to 1.0)

valid_start_date

string

Start date when the mapping became valid

valid_end_date

string

End date when the mapping expires

source_concept_code

string

Original source code in the source vocabulary

invalid_reason

string

Reason if the mapping is invalid, null otherwise

mapping_type

string

Classification of the mapping: direct, equivalent, broader, narrower, or related

meta

object

Response metadata

Show meta

request_id

string

Unique request identifier for tracing and support

timestamp

string

ISO 8601 timestamp of when the request was processed

vocab_release

string

Vocabulary release version used for this request

curl -X POST "https://api.omophub.com/v1/concepts/map" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_codes": [
      {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
      {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"}
    ],
    "target_vocabulary": "SNOMED",
    "mapping_type": "direct"
  }'

curl -X POST "https://api.omophub.com/v1/concepts/map" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_concepts": [45576876, 45591524],
    "target_vocabulary": "SNOMED",
    "mapping_type": "direct",
    "include_invalid": false
  }'

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

const client = new OMOPHub();
// Map ICD-10 codes to SNOMED. `sourceCodes` and `sourceConcepts` are XOR
// (use one or the other, never both).
const { data } = await client.mappings.map({
  sourceCodes: [
    { vocabulary_id: 'ICD10CM', concept_code: 'E11.9' },
    { vocabulary_id: 'ICD10CM', concept_code: 'I21.9' },
  ],
  targetVocabulary: 'SNOMED',
  mappingType: 'direct',
});

import requests

url = "https://api.omophub.com/v1/concepts/map"

# Map ICD-10 codes to SNOMED standard concepts
payload = {
    "source_codes": [
        {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
        {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"}
    ],
    "target_vocabulary": "SNOMED",
    "mapping_type": "direct"
}

response = requests.post(
    url,
    json=payload,
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

{
  "success": true,
  "data": {
    "mappings": [
      {
        "source_concept_id": 45576876,
        "source_concept_name": "Type 2 diabetes mellitus without complications",
        "source_concept_code": "E11.9",
        "source_vocabulary_id": "ICD10CM",
        "target_concept_id": 201826,
        "target_concept_name": "Type 2 diabetes mellitus",
        "target_concept_code": "44054006",
        "target_vocabulary_id": "SNOMED",
        "relationship_id": "Maps to",
        "relationship_name": "Maps to",
        "valid_start_date": "2023-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null,
        "mapping_confidence": 1.0,
        "mapping_type": "direct"
      },
      {
        "source_concept_id": 45591524,
        "source_concept_name": "Acute myocardial infarction, unspecified",
        "source_concept_code": "I21.9",
        "source_vocabulary_id": "ICD10CM",
        "target_concept_id": 4329847,
        "target_concept_name": "Myocardial infarction",
        "target_concept_code": "22298006",
        "target_vocabulary_id": "SNOMED",
        "relationship_id": "Maps to",
        "relationship_name": "Maps to",
        "valid_start_date": "2023-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null,
        "mapping_confidence": 1.0,
        "mapping_type": "direct"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-05T12:00:00.000Z",
    "vocab_release": "2025.1"
  }
}

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:

{
  "source_codes": [
    {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
    {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"}
  ],
  "target_vocabulary": "SNOMED",
  "mapping_type": "direct"
}

Cross-System Integration

Map multiple ICD-10 codes for EHR standardization:

{
  "source_codes": [
    {"vocabulary_id": "ICD10CM", "concept_code": "E11.9"},
    {"vocabulary_id": "ICD10CM", "concept_code": "I21.9"},
    {"vocabulary_id": "ICD10CM", "concept_code": "J44.1"}
  ],
  "target_vocabulary": "SNOMED",
  "mapping_type": "direct",
  "include_invalid": false
}

Drug Mapping

Map drug codes from NDC to RxNorm:

{
  "source_codes": [
    {"vocabulary_id": "NDC", "concept_code": "00002-4462-30"},
    {"vocabulary_id": "NDC", "concept_code": "00093-3147-01"}
  ],
  "target_vocabulary": "RxNorm",
  "mapping_type": "equivalent"
}

Using OMOP Concept IDs

If you already have OMOP concept IDs (e.g., from a search result), use source_concepts instead of source_codes:

{
  "source_concepts": [45576876, 45591524],
  "target_vocabulary": "SNOMED",
  "mapping_type": "direct"
}

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}.

Batch Map Concepts - Batch mapping operations
Get Concept Mappings - Get mappings for a specific concept
Validate Mappings - Validate mapping accuracy

Get Concept Hierarchy Get Concept Mappings

API Reference

Search

Concepts

Concept Hierarchy

Mappings

FHIR Resolver

Relationships

Domains & Classifications

Vocabularies

Overview

Request Body

Query Parameters

Response

Understanding OMOP Mapping Direction

Usage Examples

ICD-10 to SNOMED (most common use case)

Cross-System Integration

Drug Mapping

Using OMOP Concept IDs

​Overview

​Request Body

​Query Parameters

​Response

​Understanding OMOP Mapping Direction

​Usage Examples

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

​Cross-System Integration

​Drug Mapping

​Using OMOP Concept IDs

​Related Endpoints

Overview

Request Body

Query Parameters

Response

Understanding OMOP Mapping Direction

Usage Examples

ICD-10 to SNOMED (most common use case)

Cross-System Integration

Drug Mapping

Using OMOP Concept IDs

Related Endpoints