Skip to main content
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"
  }'

{
  "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)
​
data
object
Contains the concept mapping results
​
meta
object
Response metadata
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"
  }'

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