Skip to main content
POST
/
v1
/
mappings
/
bulk
curl -X POST "https://api.omophub.com/v1/mappings/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_ids": [201826, 320128, 4329847, 1503297, 4273391],
    "target_vocabularies": ["ICD10CM", "ICD10", "HCPCS"],
    "include_mapping_quality": true,
    "include_synonyms": true,
    "quality_threshold": 0.8
  }'

{
  "success": true,
  "data": {
    "request_summary": {
      "total_concepts_requested": 5,
      "concepts_found": 5,
      "concepts_not_found": 0,
      "concepts_with_mappings": 4,
      "concepts_without_mappings": 1,
      "total_mappings_found": 27,
      "target_vocabularies_requested": ["ICD10CM", "ICD10", "HCPCS"]
    },
    "concept_mappings": [
      {
        "source_concept": {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding"
        },
        "mappings": [
          {
            "mapping_id": "map_201826_45757292",
            "mapping_type": "Maps to",
            "direction": "outgoing",
            "target_concept": {
              "concept_id": 45757292,
              "concept_name": "Type 2 diabetes mellitus",
              "concept_code": "E11",
              "vocabulary_id": "ICD10CM",
              "vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
              "domain_id": "Condition",
              "concept_class_id": "3-char billing code",
              "standard_concept": "S",
              "synonyms": [
                {
                  "concept_synonym_name": "Type II diabetes mellitus",
                  "language_concept_id": 4180186,
                  "language_concept_name": "English"
                }
              ]
            },
            "mapping_quality": {
              "confidence_score": 0.98,
              "equivalence_type": "exact",
              "semantic_similarity": 0.95,
              "mapping_source": "official",
              "validation_status": "validated"
            }
          },
          {
            "mapping_id": "map_201826_4087682",
            "mapping_type": "Maps to",
            "direction": "outgoing",
            "target_concept": {
              "concept_id": 4087682,
              "concept_name": "Type 2 diabetes mellitus",
              "concept_code": "E11.9",
              "vocabulary_id": "ICD10",
              "vocabulary_name": "International Classification of Diseases, Tenth Revision",
              "domain_id": "Condition",
              "concept_class_id": "ICD10 code",
              "standard_concept": "S"
            },
            "mapping_quality": {
              "confidence_score": 0.94,
              "equivalence_type": "exact",
              "semantic_similarity": 0.92,
              "mapping_source": "official",
              "validation_status": "validated"
            }
          }
        ],
        "mapping_summary": {
          "total_mappings": 2,
          "mappings_by_vocabulary": {
            "ICD10CM": 1,
            "ICD10": 1
          },
          "mappings_by_type": {
            "Maps to": 2
          },
          "average_quality_score": 0.96
        }
      },
      {
        "source_concept": {
          "concept_id": 4273391,
          "concept_name": "Coronary artery bypass graft",
          "concept_code": "232717009",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
          "domain_id": "Procedure",
          "concept_class_id": "Procedure"
        },
        "mappings": [
          {
            "mapping_id": "map_4273391_4336464",
            "mapping_type": "Maps to",
            "direction": "outgoing",
            "target_concept": {
              "concept_id": 4336464,
              "concept_name": "Coronary artery bypass, using venous graft(s) and arterial graft(s); single vein graft (List separately in addition to code for primary procedure)",
              "concept_code": "C1520",
              "vocabulary_id": "HCPCS",
              "vocabulary_name": "Healthcare Common Procedure Coding System",
              "domain_id": "Procedure",
              "concept_class_id": "HCPCS",
              "standard_concept": "S"
            },
            "mapping_quality": {
              "confidence_score": 0.87,
              "equivalence_type": "broader",
              "semantic_similarity": 0.81,
              "mapping_source": "official",
              "validation_status": "validated"
            }
          }
        ],
        "mapping_summary": {
          "total_mappings": 1,
          "mappings_by_vocabulary": {
            "HCPCS": 1
          },
          "mappings_by_type": {
            "Maps to": 1
          },
          "average_quality_score": 0.87
        }
      }
    ],
    "not_found_concepts": [],
    "bulk_statistics": {
      "processing_time_ms": 156.7,
      "average_mappings_per_concept": 5.4,
      "most_mapped_vocabulary": "ICD10CM",
      "least_mapped_vocabulary": "HCPCS",
      "concepts_by_mapping_count": {
        "0": 1,
        "1-5": 2,
        "6-10": 1,
        "11+": 1
      },
      "quality_distribution": {
        "high_quality": 18,
        "medium_quality": 7,
        "low_quality": 2
      }
    }
  },
  "meta": {
    "request_id": "req_bulk_mappings_456789",
    "timestamp": "2024-12-22T10:45:00Z",
    "vocab_release": "2025.2"
  }
}
This endpoint enables efficient batch processing of concept mappings, essential for large-scale data transformation, ETL processes, and bulk vocabulary translation operations. It’s optimized for performance when mapping hundreds or thousands of concepts.

​
Request Body

​
concept_ids
array
required
Array of concept IDs to retrieve mappings for
Maximum: 1000 concepts per request
Example: [201826, 320128, 4329847]
​
target_vocabularies
array
Filter mappings to specific target vocabularies
Example: ["ICD10CM", "ICD10", "HCPCS"]
​
mapping_types
array
Filter by specific mapping relationship types
Default: ["Maps to", "Mapped from"]
Example: ["Maps to", "Maps to value"]
​
direction
string
default:"both"
Direction of mappings to retrieve
Options: outgoing, incoming, both
​
include_mapping_quality
boolean
default:"false"
Include mapping quality scores and metadata
​
include_synonyms
boolean
default:"false"
Include synonym information for mapped concepts
​
standard_only
boolean
default:"true"
Only return mappings to standard concepts
​
active_only
boolean
default:"true"
Only include mappings to active concepts
​
quality_threshold
number
Minimum mapping quality score (0-1)
Example: 0.8
​
group_by_source
boolean
default:"true"
Group response by source concept for easier processing
When false: Response returns a flat mappings array with {source_concept, target_concept, ...} objects.
​
include_unmapped
boolean
default:"true"
Include source concepts that have no mappings in results
​
max_mappings_per_concept
integer
Maximum number of mappings to return per concept
Default: No limit
Example: 10

​
Response

​
request_summary
object
Summary of the bulk mapping request
​
concept_mappings
array
Mappings grouped by source concept
​
not_found_concepts
array
Concept IDs that were not found in the database
​
bulk_statistics
object
Overall statistics for the bulk operation
curl -X POST "https://api.omophub.com/v1/mappings/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "concept_ids": [201826, 320128, 4329847, 1503297, 4273391],
    "target_vocabularies": ["ICD10CM", "ICD10", "HCPCS"],
    "include_mapping_quality": true,
    "include_synonyms": true,
    "quality_threshold": 0.8
  }'

{
  "success": true,
  "data": {
    "request_summary": {
      "total_concepts_requested": 5,
      "concepts_found": 5,
      "concepts_not_found": 0,
      "concepts_with_mappings": 4,
      "concepts_without_mappings": 1,
      "total_mappings_found": 27,
      "target_vocabularies_requested": ["ICD10CM", "ICD10", "HCPCS"]
    },
    "concept_mappings": [
      {
        "source_concept": {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding"
        },
        "mappings": [
          {
            "mapping_id": "map_201826_45757292",
            "mapping_type": "Maps to",
            "direction": "outgoing",
            "target_concept": {
              "concept_id": 45757292,
              "concept_name": "Type 2 diabetes mellitus",
              "concept_code": "E11",
              "vocabulary_id": "ICD10CM",
              "vocabulary_name": "International Classification of Diseases, Tenth Revision, Clinical Modification",
              "domain_id": "Condition",
              "concept_class_id": "3-char billing code",
              "standard_concept": "S",
              "synonyms": [
                {
                  "concept_synonym_name": "Type II diabetes mellitus",
                  "language_concept_id": 4180186,
                  "language_concept_name": "English"
                }
              ]
            },
            "mapping_quality": {
              "confidence_score": 0.98,
              "equivalence_type": "exact",
              "semantic_similarity": 0.95,
              "mapping_source": "official",
              "validation_status": "validated"
            }
          },
          {
            "mapping_id": "map_201826_4087682",
            "mapping_type": "Maps to",
            "direction": "outgoing",
            "target_concept": {
              "concept_id": 4087682,
              "concept_name": "Type 2 diabetes mellitus",
              "concept_code": "E11.9",
              "vocabulary_id": "ICD10",
              "vocabulary_name": "International Classification of Diseases, Tenth Revision",
              "domain_id": "Condition",
              "concept_class_id": "ICD10 code",
              "standard_concept": "S"
            },
            "mapping_quality": {
              "confidence_score": 0.94,
              "equivalence_type": "exact",
              "semantic_similarity": 0.92,
              "mapping_source": "official",
              "validation_status": "validated"
            }
          }
        ],
        "mapping_summary": {
          "total_mappings": 2,
          "mappings_by_vocabulary": {
            "ICD10CM": 1,
            "ICD10": 1
          },
          "mappings_by_type": {
            "Maps to": 2
          },
          "average_quality_score": 0.96
        }
      },
      {
        "source_concept": {
          "concept_id": 4273391,
          "concept_name": "Coronary artery bypass graft",
          "concept_code": "232717009",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
          "domain_id": "Procedure",
          "concept_class_id": "Procedure"
        },
        "mappings": [
          {
            "mapping_id": "map_4273391_4336464",
            "mapping_type": "Maps to",
            "direction": "outgoing",
            "target_concept": {
              "concept_id": 4336464,
              "concept_name": "Coronary artery bypass, using venous graft(s) and arterial graft(s); single vein graft (List separately in addition to code for primary procedure)",
              "concept_code": "C1520",
              "vocabulary_id": "HCPCS",
              "vocabulary_name": "Healthcare Common Procedure Coding System",
              "domain_id": "Procedure",
              "concept_class_id": "HCPCS",
              "standard_concept": "S"
            },
            "mapping_quality": {
              "confidence_score": 0.87,
              "equivalence_type": "broader",
              "semantic_similarity": 0.81,
              "mapping_source": "official",
              "validation_status": "validated"
            }
          }
        ],
        "mapping_summary": {
          "total_mappings": 1,
          "mappings_by_vocabulary": {
            "HCPCS": 1
          },
          "mappings_by_type": {
            "Maps to": 1
          },
          "average_quality_score": 0.87
        }
      }
    ],
    "not_found_concepts": [],
    "bulk_statistics": {
      "processing_time_ms": 156.7,
      "average_mappings_per_concept": 5.4,
      "most_mapped_vocabulary": "ICD10CM",
      "least_mapped_vocabulary": "HCPCS",
      "concepts_by_mapping_count": {
        "0": 1,
        "1-5": 2,
        "6-10": 1,
        "11+": 1
      },
      "quality_distribution": {
        "high_quality": 18,
        "medium_quality": 7,
        "low_quality": 2
      }
    }
  },
  "meta": {
    "request_id": "req_bulk_mappings_456789",
    "timestamp": "2024-12-22T10:45:00Z",
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

​
Basic Bulk Mapping

Map multiple concepts to ICD-10-CM: 
const response = await fetch('/v1/mappings/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    concept_ids: [201826, 320128, 4329847],
    target_vocabularies: ['ICD10CM']
  })
});

​
High-Quality Mappings Only

Get only high-confidence mappings: 
const qualityMappings = await fetch('/v1/mappings/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    concept_ids: conceptIds,
    quality_threshold: 0.9,
    include_mapping_quality: true,
    max_mappings_per_concept: 5
  })
});

​
ETL Pipeline Integration

Optimized for data transformation pipelines: 
const etlMappings = await fetch('/v1/mappings/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    concept_ids: largeBatchOfConceptIds,
    target_vocabularies: ['ICD10CM', 'HCPCS'],
    direction: 'outgoing',
    standard_only: true,
    group_by_source: true,
    include_unmapped: false
  })
});

​
Cross-Vocabulary Translation

Translate concepts across multiple vocabularies: 
const translation = await fetch('/v1/mappings/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    concept_ids: snomedConceptIds,
    target_vocabularies: ['ICD10CM', 'ICD10', 'HCPCS', 'NDC'],
    include_synonyms: true,
    max_mappings_per_concept: 10
  })
});

​
Data Quality Assessment

Assess mapping quality for a concept set: 
const qualityAssessment = await fetch('/v1/mappings/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    concept_ids: conceptsToAssess,
    include_mapping_quality: true,
    include_synonyms: false,
    direction: 'both'
  })
});

​
Notes

  • Maximum 1000 concepts per request to maintain performance
  • Bulk operations are optimized for throughput over individual response detail
  • Use quality thresholds to filter unreliable mappings in production
  • Group by source simplifies client-side processing of results
  • Include unmapped concepts to identify gaps in coverage
  • Processing time scales with number of concepts and complexity of filters
  • Consider pagination strategies for very large concept sets
  • Results are cached briefly to improve repeated request performance