Batch Map Concepts

curl -X POST "https://api.omophub.com/v1/concepts/map/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [
      {
        "concept_id": 201826,
        "target_vocabularies": ["ICD10CM", "ICD9CM"],
        "include_approximate": true,
        "context_id": "diabetes_mapping"
      },
      {
        "concept_id": 4182210,
        "target_vocabularies": ["ICD10CM", "SNOMED"],
        "standard_concepts_only": true,
        "max_mappings_per_concept": 5
      },
      {
        "concept_id": 313217,
        "target_vocabularies": ["ICD10CM", "ICD9CM"],
        "mapping_types": ["Maps to", "Maps to value"]
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "concept_id": 201826,
        "success": true,
        "context_id": "diabetes_study",
        "source_concept": {
          "concept_name": "Type 2 diabetes mellitus",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "concept_code": "44054006"
        },
        "mappings": [
          {
            "target_vocabulary": "ICD10CM",
            "mapped_concepts": [
              {
                "concept_id": 443735,
                "concept_name": "Type 2 diabetes mellitus without complications",
                "concept_code": "E11.9",
                "domain_id": "Condition",
                "concept_class_id": "4-char billing code",
                "standard_concept": null,
                "mapping_type": "Maps to",
                "mapping_confidence": 0.95,
                "is_approximate": false,
                "valid_start_date": "2015-10-01",
                "valid_end_date": "2099-12-31"
              },
              {
                "concept_id": 443767,
                "concept_name": "Type 2 diabetes mellitus with complications",
                "concept_code": "E11",
                "domain_id": "Condition",
                "concept_class_id": "3-char nonbill code",
                "standard_concept": null,
                "mapping_type": "Maps to",
                "mapping_confidence": 0.88,
                "is_approximate": true,
                "valid_start_date": "2015-10-01",
                "valid_end_date": "2099-12-31"
              }
            ],
            "mapping_summary": {
              "total_mappings": 2,
              "exact_mappings": 1,
              "approximate_mappings": 1,
              "mapping_quality": "good",
              "coverage_completeness": 0.85
            }
          },
          {
            "target_vocabulary": "ICD9CM",
            "mapped_concepts": [
              {
                "concept_id": 44054361,
                "concept_name": "Diabetes mellitus without mention of complication, type II or unspecified type, not stated as uncontrolled",
                "concept_code": "250.00",
                "domain_id": "Condition",
                "concept_class_id": "5-dig billing code",
                "standard_concept": null,
                "mapping_type": "Maps to",
                "mapping_confidence": 0.92,
                "is_approximate": false,
                "valid_start_date": "1970-01-01",
                "valid_end_date": "2015-09-30"
              }
            ],
            "mapping_summary": {
              "total_mappings": 1,
              "exact_mappings": 1,
              "approximate_mappings": 0,
              "mapping_quality": "excellent",
              "coverage_completeness": 0.95
            }
          }
        ],
        "overall_summary": {
          "total_target_vocabularies": 2,
          "successful_vocabularies": 2,
          "total_mapped_concepts": 3,
          "best_mapping_quality": "excellent",
          "has_standard_mappings": false
        }
      }
    ],
    "batch_summary": {
      "total_concepts": 1,
      "successful_mappings": 1,
      "failed_mappings": 0,
      "total_mapped_concepts": 3,
      "vocabulary_coverage": {
        "ICD10CM": {
          "total_attempts": 1,
          "mapped_concepts": 2,
          "success_rate": 100.0
        },
        "ICD9CM": {
          "total_attempts": 1,
          "mapped_concepts": 1,
          "success_rate": 100.0
        }
      },
      "processing_time_ms": 245,
      "cache_hit_rate": 45.5
    }
  },
  "meta": {
    "request_id": "req_batch_map_concepts_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

curl -X POST "https://api.omophub.com/v1/concepts/map/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [
      {
        "concept_id": 201826,
        "target_vocabularies": ["ICD10CM", "ICD9CM"],
        "include_approximate": true,
        "context_id": "diabetes_mapping"
      },
      {
        "concept_id": 4182210,
        "target_vocabularies": ["ICD10CM", "SNOMED"],
        "standard_concepts_only": true,
        "max_mappings_per_concept": 5
      },
      {
        "concept_id": 313217,
        "target_vocabularies": ["ICD10CM", "ICD9CM"],
        "mapping_types": ["Maps to", "Maps to value"]
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "concept_id": 201826,
        "success": true,
        "context_id": "diabetes_study",
        "source_concept": {
          "concept_name": "Type 2 diabetes mellitus",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "concept_code": "44054006"
        },
        "mappings": [
          {
            "target_vocabulary": "ICD10CM",
            "mapped_concepts": [
              {
                "concept_id": 443735,
                "concept_name": "Type 2 diabetes mellitus without complications",
                "concept_code": "E11.9",
                "domain_id": "Condition",
                "concept_class_id": "4-char billing code",
                "standard_concept": null,
                "mapping_type": "Maps to",
                "mapping_confidence": 0.95,
                "is_approximate": false,
                "valid_start_date": "2015-10-01",
                "valid_end_date": "2099-12-31"
              },
              {
                "concept_id": 443767,
                "concept_name": "Type 2 diabetes mellitus with complications",
                "concept_code": "E11",
                "domain_id": "Condition",
                "concept_class_id": "3-char nonbill code",
                "standard_concept": null,
                "mapping_type": "Maps to",
                "mapping_confidence": 0.88,
                "is_approximate": true,
                "valid_start_date": "2015-10-01",
                "valid_end_date": "2099-12-31"
              }
            ],
            "mapping_summary": {
              "total_mappings": 2,
              "exact_mappings": 1,
              "approximate_mappings": 1,
              "mapping_quality": "good",
              "coverage_completeness": 0.85
            }
          },
          {
            "target_vocabulary": "ICD9CM",
            "mapped_concepts": [
              {
                "concept_id": 44054361,
                "concept_name": "Diabetes mellitus without mention of complication, type II or unspecified type, not stated as uncontrolled",
                "concept_code": "250.00",
                "domain_id": "Condition",
                "concept_class_id": "5-dig billing code",
                "standard_concept": null,
                "mapping_type": "Maps to",
                "mapping_confidence": 0.92,
                "is_approximate": false,
                "valid_start_date": "1970-01-01",
                "valid_end_date": "2015-09-30"
              }
            ],
            "mapping_summary": {
              "total_mappings": 1,
              "exact_mappings": 1,
              "approximate_mappings": 0,
              "mapping_quality": "excellent",
              "coverage_completeness": 0.95
            }
          }
        ],
        "overall_summary": {
          "total_target_vocabularies": 2,
          "successful_vocabularies": 2,
          "total_mapped_concepts": 3,
          "best_mapping_quality": "excellent",
          "has_standard_mappings": false
        }
      }
    ],
    "batch_summary": {
      "total_concepts": 1,
      "successful_mappings": 1,
      "failed_mappings": 0,
      "total_mapped_concepts": 3,
      "vocabulary_coverage": {
        "ICD10CM": {
          "total_attempts": 1,
          "mapped_concepts": 2,
          "success_rate": 100.0
        },
        "ICD9CM": {
          "total_attempts": 1,
          "mapped_concepts": 1,
          "success_rate": 100.0
        }
      },
      "processing_time_ms": 245,
      "cache_hit_rate": 45.5
    }
  },
  "meta": {
    "request_id": "req_batch_map_concepts_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

Overview

This endpoint allows you to map multiple concepts from source vocabularies to target vocabularies in a single API call. It’s optimized for bulk operations and provides significant performance benefits when working with large sets of concept mappings.

Request Body

mappings

array

required

Array of concept mapping requests

Show mappings

concept_id

integer

required

The OMOP concept ID to map from

target_vocabularies

array

required

Array of target vocabulary IDs to map to (e.g., [“ICD10CM”, “ICD9CM”])

mapping_types

array

Array of mapping relationship types to use (default: [“Maps to”, “Maps to value”])

include_approximate

boolean

default:"false"

Include approximate mappings when exact mappings are not available

standard_concepts_only

boolean

default:"false"

When true, only mappings to standard concepts are returned (non-standard codes like ICD9/ICD10 will be excluded)

max_mappings_per_concept

integer

default:"10"

Maximum number of mappings to return per source concept

context_id

string

Optional context identifier for tracking related mappings

Query Parameters

vocab_release

string

Specific vocabulary release version (e.g., “2024.1”)

include_source_details

boolean

default:"true"

Include full source concept details in responses

include_mapping_confidence

boolean

default:"false"

Include confidence scores for mappings

Response

success

boolean

required

Indicates if the batch mapping request was successful

data

object

required

Response data containing batch mapping results

Show data

results

array

Array of mapping results matching the input order

Show results

concept_id

integer

The source concept ID that was mapped

success

boolean

Whether this individual mapping succeeded

error

string

Error message if the mapping failed

context_id

string

Context identifier if provided in request

source_concept

object

Source concept information (when include_source_details=true)

Show source_concept

concept_name

string

Source concept name

vocabulary_id

string

Source vocabulary

domain_id

string

Source domain

concept_class_id

string

Source concept class

standard_concept

string

Standard concept flag

concept_code

string

Source concept code

mappings

array

Array of target vocabulary mappings

Show mappings

target_vocabulary

string

Target vocabulary ID

mapped_concepts

array

Array of concepts in the target vocabulary

Show mapped_concepts

concept_id

integer

Mapped concept ID

concept_name

string

Mapped concept name

concept_code

string

Mapped concept code

domain_id

string

Mapped concept domain

concept_class_id

string

Mapped concept class

standard_concept

string

Standard concept flag

mapping_type

string

Type of mapping relationship

mapping_confidence

number

Confidence score (0.0-1.0) when include_mapping_confidence=true

is_approximate

boolean

Whether this is an approximate mapping

valid_start_date

string

When mapping became valid

valid_end_date

string

When mapping expires

mapping_summary

object

Summary for this target vocabulary

Show mapping_summary

total_mappings

integer

Number of mappings found

exact_mappings

integer

Number of exact mappings

approximate_mappings

integer

Number of approximate mappings

mapping_quality

string

Overall mapping quality: “excellent”, “good”, “fair”, “poor”

coverage_completeness

number

Coverage completeness score (0.0-1.0)

overall_summary

object

Overall mapping summary for this concept

Show overall_summary

total_target_vocabularies

integer

Number of target vocabularies processed

successful_vocabularies

integer

Number of vocabularies with successful mappings

total_mapped_concepts

integer

Total concepts mapped across all vocabularies

best_mapping_quality

string

Best mapping quality achieved

has_standard_mappings

boolean

Whether any standard concept mappings were found

batch_summary

object

Summary statistics for the entire batch

Show batch_summary

total_concepts

integer

Total number of concepts to map

successful_mappings

integer

Number of concepts with successful mappings

failed_mappings

integer

Number of concepts with no mappings found

total_mapped_concepts

integer

Total target concepts found across all mappings

vocabulary_coverage

object

Coverage statistics by target vocabulary. Map from vocabulary name to coverage details.

Show vocabulary_coverage

[vocabulary_name]

object

Coverage statistics for a specific target vocabulary (e.g., “ICD10CM”, “ICD9CM”)

Show Vocabulary Statistics

total_attempts

integer

Number of mapping attempts to this vocabulary

mapped_concepts

integer

Number of successfully mapped concepts

success_rate

number

Success rate as percentage (0.0-100.0)

processing_time_ms

integer

Total processing time for batch

cache_hit_rate

number

Percentage of mappings served from cache

meta

object

required

Response metadata and API information

Show meta

request_id

string

Unique request identifier for debugging

timestamp

string

ISO 8601 timestamp of the response

vocab_release

string

Vocabulary release version used

curl -X POST "https://api.omophub.com/v1/concepts/map/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [
      {
        "concept_id": 201826,
        "target_vocabularies": ["ICD10CM", "ICD9CM"],
        "include_approximate": true,
        "context_id": "diabetes_mapping"
      },
      {
        "concept_id": 4182210,
        "target_vocabularies": ["ICD10CM", "SNOMED"],
        "standard_concepts_only": true,
        "max_mappings_per_concept": 5
      },
      {
        "concept_id": 313217,
        "target_vocabularies": ["ICD10CM", "ICD9CM"],
        "mapping_types": ["Maps to", "Maps to value"]
      }
    ]
  }'

{
  "success": true,
  "data": {
    "results": [
      {
        "concept_id": 201826,
        "success": true,
        "context_id": "diabetes_study",
        "source_concept": {
          "concept_name": "Type 2 diabetes mellitus",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "concept_code": "44054006"
        },
        "mappings": [
          {
            "target_vocabulary": "ICD10CM",
            "mapped_concepts": [
              {
                "concept_id": 443735,
                "concept_name": "Type 2 diabetes mellitus without complications",
                "concept_code": "E11.9",
                "domain_id": "Condition",
                "concept_class_id": "4-char billing code",
                "standard_concept": null,
                "mapping_type": "Maps to",
                "mapping_confidence": 0.95,
                "is_approximate": false,
                "valid_start_date": "2015-10-01",
                "valid_end_date": "2099-12-31"
              },
              {
                "concept_id": 443767,
                "concept_name": "Type 2 diabetes mellitus with complications",
                "concept_code": "E11",
                "domain_id": "Condition",
                "concept_class_id": "3-char nonbill code",
                "standard_concept": null,
                "mapping_type": "Maps to",
                "mapping_confidence": 0.88,
                "is_approximate": true,
                "valid_start_date": "2015-10-01",
                "valid_end_date": "2099-12-31"
              }
            ],
            "mapping_summary": {
              "total_mappings": 2,
              "exact_mappings": 1,
              "approximate_mappings": 1,
              "mapping_quality": "good",
              "coverage_completeness": 0.85
            }
          },
          {
            "target_vocabulary": "ICD9CM",
            "mapped_concepts": [
              {
                "concept_id": 44054361,
                "concept_name": "Diabetes mellitus without mention of complication, type II or unspecified type, not stated as uncontrolled",
                "concept_code": "250.00",
                "domain_id": "Condition",
                "concept_class_id": "5-dig billing code",
                "standard_concept": null,
                "mapping_type": "Maps to",
                "mapping_confidence": 0.92,
                "is_approximate": false,
                "valid_start_date": "1970-01-01",
                "valid_end_date": "2015-09-30"
              }
            ],
            "mapping_summary": {
              "total_mappings": 1,
              "exact_mappings": 1,
              "approximate_mappings": 0,
              "mapping_quality": "excellent",
              "coverage_completeness": 0.95
            }
          }
        ],
        "overall_summary": {
          "total_target_vocabularies": 2,
          "successful_vocabularies": 2,
          "total_mapped_concepts": 3,
          "best_mapping_quality": "excellent",
          "has_standard_mappings": false
        }
      }
    ],
    "batch_summary": {
      "total_concepts": 1,
      "successful_mappings": 1,
      "failed_mappings": 0,
      "total_mapped_concepts": 3,
      "vocabulary_coverage": {
        "ICD10CM": {
          "total_attempts": 1,
          "mapped_concepts": 2,
          "success_rate": 100.0
        },
        "ICD9CM": {
          "total_attempts": 1,
          "mapped_concepts": 1,
          "success_rate": 100.0
        }
      },
      "processing_time_ms": 245,
      "cache_hit_rate": 45.5
    }
  },
  "meta": {
    "request_id": "req_batch_map_concepts_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.2"
  }
}

Usage Examples

Basic Batch Mapping

Map concepts to common coding systems:

{
  "mappings": [
    {
      "concept_id": 201826,
      "target_vocabularies": ["ICD10CM", "ICD9CM"]
    },
    {
      "concept_id": 4182210,
      "target_vocabularies": ["ICD10CM", "HCPCS"]
    }
  ]
}

High-Quality Mappings Only

Get only exact, standard concept mappings:

{
  "mappings": [
    {
      "concept_id": 201826,
      "target_vocabularies": ["ICD10CM", "SNOMED"],
      "include_approximate": false,
      "standard_concepts_only": true,
      "max_mappings_per_concept": 3
    }
  ]
}

Research Context Mapping

Map concepts with context tracking:

{
  "mappings": [
    {
      "concept_id": 201826,
      "target_vocabularies": ["ICD10CM", "ICD9CM", "HCPCS"],
      "context_id": "diabetes_outcome_study_2024",
      "include_approximate": true,
      "mapping_types": ["Maps to", "Maps to value"]
    }
  ]
}

Important Notes

Batch size limit: Maximum 200 mapping requests per batch
Performance optimization: Batch processing is significantly more efficient than individual requests
Error isolation: Individual mapping failures don’t affect other mappings in the batch
Result ordering: Results are returned in the same order as input mappings
Confidence scores: Available when include_mapping_confidence=true but increase processing time
Context tracking: Use context_id for tracking related mappings across requests

Map Concepts - Single concept mapping
Validate Mappings - Validate existing mappings
Get Mapping Coverage - Vocabulary mapping coverage analysis

Get Concept Mappings Validate Mappings

⌘I

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Batch Mapping

High-Quality Mappings Only

Research Context Mapping

Important Notes

API Reference

Concepts

Concept Hierarchy

Search

Search (Coming Soon)

Relationships

Domains & Classifications

Mappings

Vocabularies

​Overview

​Request Body

​Query Parameters

​Response

​Usage Examples

​Basic Batch Mapping

​High-Quality Mappings Only

​Research Context Mapping

​Important Notes

​Related Endpoints

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Batch Mapping

High-Quality Mappings Only

Research Context Mapping

Important Notes

Related Endpoints