> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Map Concepts

> Perform multiple OMOP concept mapping operations in a single batched request - high-throughput cross-vocabulary translation for ETL pipelines.

## Overview

This endpoint allows you to perform multiple concept mapping operations in a single API call. Each mapping request maps a set of source concepts to a target vocabulary, enabling efficient bulk processing.

## Request Body

<ParamField body="mapping_requests" type="array" required>
  Array of mapping requests (1-50 items)

  <Expandable title="mapping_requests">
    <ParamField body="request_id" type="string" required>
      Unique identifier for this mapping request (for tracking results)
    </ParamField>

    <ParamField body="source_concepts" type="array[integer]" required>
      Array of OMOP concept IDs to map (minimum 1 integer)
    </ParamField>

    <ParamField body="target_vocabulary" type="string" required>
      Target vocabulary ID to map to (e.g., "ICD10CM", "SNOMED", "ICD9CM")
    </ParamField>
  </Expandable>
</ParamField>

## Query Parameters

<ParamField query="vocab_release" type="string">
  Specific vocabulary release version (e.g., "2025.1")
</ParamField>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates if the batch request was processed successfully
</ResponseField>

<ResponseField name="data" type="array" required>
  Array of mapping results matching the input order

  <Expandable title="data">
    <ResponseField name="request_id" type="string">
      The request ID provided in the input
    </ResponseField>

    <ResponseField name="source_concepts" type="array">
      Array of source concept IDs that were mapped
    </ResponseField>

    <ResponseField name="target_vocabulary" type="string">
      The target vocabulary for this mapping request
    </ResponseField>

    <ResponseField name="mappings" type="array">
      Array of concept mappings found

      <Expandable title="mappings">
        <ResponseField name="source_concept_id" type="integer">
          The source OMOP concept ID that was mapped
        </ResponseField>

        <ResponseField name="target_concept_id" type="integer">
          The target OMOP concept ID in the target vocabulary
        </ResponseField>

        <ResponseField name="target_concept_name" type="string">
          Human-readable name of the target concept
        </ResponseField>

        <ResponseField name="target_concept_code" type="string">
          The code of the target concept in its vocabulary
        </ResponseField>

        <ResponseField name="relationship_id" type="string">
          The relationship type (e.g., "Maps to", "Maps to value")
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="success" type="boolean">
      Whether this individual mapping request succeeded
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message if the mapping request failed (null if successful)
    </ResponseField>

    <ResponseField name="request_index" type="integer">
      Index of this request in the original input array
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object" required>
  Response metadata and API information

  <Expandable title="meta">
    <ResponseField name="request_id" type="string">
      Unique request identifier for debugging
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of the response
    </ResponseField>

    <ResponseField name="vocab_release" type="string">
      Vocabulary release version used
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.omophub.com/v1/concepts/map/batch" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mapping_requests": [
        {
          "request_id": "diabetes_icd10",
          "source_concepts": [201826, 443735],
          "target_vocabulary": "ICD10CM"
        },
        {
          "request_id": "hypertension_snomed",
          "source_concepts": [4182210],
          "target_vocabulary": "SNOMED"
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.omophub.com/v1/concepts/map/batch', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      mapping_requests: [
        {
          request_id: "diabetes_icd10",
          source_concepts: [201826, 443735],
          target_vocabulary: "ICD10CM"
        },
        {
          request_id: "hypertension_snomed",
          source_concepts: [4182210],
          target_vocabulary: "SNOMED"
        }
      ]
    })
  });

  const result = await response.json();
  for (const item of result.data) {
    console.log(`Request ${item.request_id}: ${item.success ? 'Success' : 'Failed'}`);
    if (item.success) {
      console.log(`  Found ${item.mappings.length} mappings to ${item.target_vocabulary}`);
    } else {
      console.log(`  Error: ${item.error}`);
    }
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.omophub.com/v1/concepts/map/batch",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "mapping_requests": [
              {
                  "request_id": "diabetes_icd10",
                  "source_concepts": [201826, 443735],
                  "target_vocabulary": "ICD10CM"
              },
              {
                  "request_id": "hypertension_snomed",
                  "source_concepts": [4182210],
                  "target_vocabulary": "SNOMED"
              }
          ]
      }
  )

  result = response.json()
  for item in result["data"]:
      status = "Success" if item["success"] else "Failed"
      print(f"Request {item['request_id']}: {status}")
      if item["success"]:
          print(f"  Found {len(item['mappings'])} mappings to {item['target_vocabulary']}")
      else:
          print(f"  Error: {item['error']}")
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "request_id": "diabetes_icd10",
        "source_concepts": [201826, 443735],
        "target_vocabulary": "ICD10CM",
        "mappings": [
          {
            "source_concept_id": 201826,
            "target_concept_id": 443735,
            "target_concept_name": "Type 2 diabetes mellitus without complications",
            "target_concept_code": "E11.9",
            "relationship_id": "Maps to"
          }
        ],
        "success": true,
        "error": null,
        "request_index": 0
      },
      {
        "request_id": "hypertension_snomed",
        "source_concepts": [4182210],
        "target_vocabulary": "SNOMED",
        "mappings": [
          {
            "source_concept_id": 4182210,
            "target_concept_id": 316866,
            "target_concept_name": "Hypertensive disorder",
            "target_concept_code": "38341003",
            "relationship_id": "Maps to"
          }
        ],
        "success": true,
        "error": null,
        "request_index": 1
      }
    ],
    "meta": {
      "request_id": "req_batch_abc123",
      "timestamp": "2024-12-22T10:00:00Z",
      "vocab_release": "2025.2"
    }
  }
  ```
</ResponseExample>

## Important Notes

* **Batch size limit**: Maximum 50 mapping requests per batch
* **Error isolation**: Individual mapping failures don't affect other mappings in the batch
* **Result ordering**: Results are returned in the same order as input requests
* **Request IDs**: Use unique `request_id` values to correlate results with your input

## Related Endpoints

* [Get Concept Mappings](/api-reference/mappings/get-concept-mappings) - Get mappings for a single concept
* [Validate Mappings](/api-reference/mappings/validate-mappings) - Validate existing mappings