Bulk Search

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "standard_concept": "S"
    },
    "searches": [
      {
        "search_id": "s1",
        "query": "diabetes"
      },
      {
        "search_id": "s2",
        "query": "hypertension"
      },
      {
        "search_id": "s3",
        "query": "aspirin",
        "vocabulary_ids": ["RxNorm"],
        "domain_ids": ["Drug"]
      }
    ]
  }'

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

const client = new OMOPHub();
// Per-search entries (BulkBasicSearchInput) use snake_case; outer
// `defaults` follows the same convention. See SDK Search docs.
const { data } = await client.search.bulkBasic(
  [
    { search_id: 's1', query: 'diabetes' },
    { search_id: 's2', query: 'hypertension' },
    { search_id: 's3', query: 'aspirin', vocabulary_ids: ['RxNorm'], domain_ids: ['Drug'] },
  ],
  { defaults: { vocabulary_ids: ['SNOMED'], standard_concept: 'S' } },
);

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
    'defaults': {
        'vocabulary_ids': ['SNOMED'],
        'standard_concept': 'S'
    },
    'searches': [
        {
            'search_id': 's1',
            'query': 'diabetes'
        },
        {
            'search_id': 's2',
            'query': 'hypertension'
        },
        {
            'search_id': 's3',
            'query': 'aspirin',
            'vocabulary_ids': ['RxNorm'],
            'domain_ids': ['Drug']
        }
    ]
}

response = requests.post(
    'https://api.omophub.com/v1/search/bulk',
    headers=headers,
    json=payload
)

data = response.json()

{
  "success": true,
  "data": [
    {
      "search_id": "s1",
      "query": "diabetes",
      "status": "completed",
      "results": [
        {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 100
        },
        {
          "concept_id": 4000678,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 90
        }
      ],
      "duration": 856
    },
    {
      "search_id": "s2",
      "query": "hypertension",
      "status": "completed",
      "results": [
        {
          "concept_id": 320128,
          "concept_name": "Essential hypertension",
          "concept_code": "59621000",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 100
        },
        {
          "concept_id": 316866,
          "concept_name": "Hypertensive disorder",
          "concept_code": "38341003",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 90
        }
      ],
      "duration": 1034
    },
    {
      "search_id": "s3",
      "query": "aspirin",
      "status": "completed",
      "results": [
        {
          "concept_id": 1112807,
          "concept_name": "Aspirin",
          "concept_code": "1191",
          "vocabulary_id": "RxNorm",
          "domain_id": "Drug",
          "concept_class_id": "Ingredient",
          "standard_concept": "S",
          "search_score": 100
        }
      ],
      "duration": 957
    }
  ],
  "meta": {
    "request_id": "req_bulk_search_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "standard_concept": "S"
    },
    "searches": [
      {
        "search_id": "s1",
        "query": "diabetes"
      },
      {
        "search_id": "s2",
        "query": "hypertension"
      },
      {
        "search_id": "s3",
        "query": "aspirin",
        "vocabulary_ids": ["RxNorm"],
        "domain_ids": ["Drug"]
      }
    ]
  }'

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

const client = new OMOPHub();
// Per-search entries (BulkBasicSearchInput) use snake_case; outer
// `defaults` follows the same convention. See SDK Search docs.
const { data } = await client.search.bulkBasic(
  [
    { search_id: 's1', query: 'diabetes' },
    { search_id: 's2', query: 'hypertension' },
    { search_id: 's3', query: 'aspirin', vocabulary_ids: ['RxNorm'], domain_ids: ['Drug'] },
  ],
  { defaults: { vocabulary_ids: ['SNOMED'], standard_concept: 'S' } },
);

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
    'defaults': {
        'vocabulary_ids': ['SNOMED'],
        'standard_concept': 'S'
    },
    'searches': [
        {
            'search_id': 's1',
            'query': 'diabetes'
        },
        {
            'search_id': 's2',
            'query': 'hypertension'
        },
        {
            'search_id': 's3',
            'query': 'aspirin',
            'vocabulary_ids': ['RxNorm'],
            'domain_ids': ['Drug']
        }
    ]
}

response = requests.post(
    'https://api.omophub.com/v1/search/bulk',
    headers=headers,
    json=payload
)

data = response.json()

{
  "success": true,
  "data": [
    {
      "search_id": "s1",
      "query": "diabetes",
      "status": "completed",
      "results": [
        {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 100
        },
        {
          "concept_id": 4000678,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 90
        }
      ],
      "duration": 856
    },
    {
      "search_id": "s2",
      "query": "hypertension",
      "status": "completed",
      "results": [
        {
          "concept_id": 320128,
          "concept_name": "Essential hypertension",
          "concept_code": "59621000",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 100
        },
        {
          "concept_id": 316866,
          "concept_name": "Hypertensive disorder",
          "concept_code": "38341003",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 90
        }
      ],
      "duration": 1034
    },
    {
      "search_id": "s3",
      "query": "aspirin",
      "status": "completed",
      "results": [
        {
          "concept_id": 1112807,
          "concept_name": "Aspirin",
          "concept_code": "1191",
          "vocabulary_id": "RxNorm",
          "domain_id": "Drug",
          "concept_class_id": "Ingredient",
          "standard_concept": "S",
          "search_score": 100
        }
      ],
      "duration": 957
    }
  ],
  "meta": {
    "request_id": "req_bulk_search_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

Overview

This endpoint allows you to submit multiple search queries in a single request, enabling efficient batch processing of search operations. It’s ideal for applications that need to search for many terms simultaneously, such as data processing pipelines, bulk concept mapping, or batch validation workflows. Each query uses full-text search with a default limit of 20 results per query (configurable via page_size, max 100). Up to 50 queries can be submitted per request.

For paginated results or semantic search, use the Basic Search or Semantic Search endpoints instead.

Request Body

array

required

Array of search query objects (1-50 items)

Show Search Object

string

required

Unique identifier for this search within the batch

string

required

Search term or phrase

boolean

default:"true"

Enable bulk-optimized search mode for better performance

string[]

Filter results to specific vocabularies (e.g., ["SNOMED", "ICD10CM"]). Overrides defaults.vocabulary_ids for this search.

string[]

Filter results to specific domains (e.g., ["Condition", "Drug"]). Overrides defaults.domain_ids for this search.

string[]

Filter results to specific concept classes (e.g., ["Clinical Finding"]). Overrides defaults.concept_class_ids for this search.

string

Filter by standard concept status: "S" (Standard) or "C" (Classification). Overrides defaults.standard_concept for this search.

boolean

default:"false"

Include invalid/deprecated concepts. Overrides defaults.include_invalid for this search.

integer

default:"20"

Number of results per search (1-100). Overrides defaults.page_size for this search.

object

Default filter parameters applied to all searches. Individual searches can override any default.

Show Defaults Object

string[]

Default vocabulary filter for all searches (e.g., ["SNOMED"])

string[]

Default domain filter for all searches (e.g., ["Condition"])

string[]

Default concept class filter for all searches

string

Default standard concept filter: "S" or "C"

boolean

default:"false"

Default invalid concept inclusion

integer

default:"20"

Default results per search (1-100)

Query Parameters

string

Specific vocabulary release version (defaults to latest)

Response

boolean

Indicates if the request was successful

array

Array of search results, one per query

Show Search Result

string

Identifier matching the request’s search_id

string

Original search query

string

Query execution status: completed or failed

array

Array of matching concepts

Show Concept Result

integer

Unique concept identifier

string

Primary concept name

string

Concept code

string

Source vocabulary

string

Domain classification

string

Concept class

string

Standard concept indicator

number

Search relevance score

string

Error message (if query failed)

number

Processing time for this query in milliseconds

object

Show Metadata

string

Unique identifier for the request

string

Request timestamp

string

Vocabulary release version used

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "standard_concept": "S"
    },
    "searches": [
      {
        "search_id": "s1",
        "query": "diabetes"
      },
      {
        "search_id": "s2",
        "query": "hypertension"
      },
      {
        "search_id": "s3",
        "query": "aspirin",
        "vocabulary_ids": ["RxNorm"],
        "domain_ids": ["Drug"]
      }
    ]
  }'

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

const client = new OMOPHub();
// Per-search entries (BulkBasicSearchInput) use snake_case; outer
// `defaults` follows the same convention. See SDK Search docs.
const { data } = await client.search.bulkBasic(
  [
    { search_id: 's1', query: 'diabetes' },
    { search_id: 's2', query: 'hypertension' },
    { search_id: 's3', query: 'aspirin', vocabulary_ids: ['RxNorm'], domain_ids: ['Drug'] },
  ],
  { defaults: { vocabulary_ids: ['SNOMED'], standard_concept: 'S' } },
);

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
    'defaults': {
        'vocabulary_ids': ['SNOMED'],
        'standard_concept': 'S'
    },
    'searches': [
        {
            'search_id': 's1',
            'query': 'diabetes'
        },
        {
            'search_id': 's2',
            'query': 'hypertension'
        },
        {
            'search_id': 's3',
            'query': 'aspirin',
            'vocabulary_ids': ['RxNorm'],
            'domain_ids': ['Drug']
        }
    ]
}

response = requests.post(
    'https://api.omophub.com/v1/search/bulk',
    headers=headers,
    json=payload
)

data = response.json()

{
  "success": true,
  "data": [
    {
      "search_id": "s1",
      "query": "diabetes",
      "status": "completed",
      "results": [
        {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 100
        },
        {
          "concept_id": 4000678,
          "concept_name": "Diabetes mellitus",
          "concept_code": "73211009",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 90
        }
      ],
      "duration": 856
    },
    {
      "search_id": "s2",
      "query": "hypertension",
      "status": "completed",
      "results": [
        {
          "concept_id": 320128,
          "concept_name": "Essential hypertension",
          "concept_code": "59621000",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 100
        },
        {
          "concept_id": 316866,
          "concept_name": "Hypertensive disorder",
          "concept_code": "38341003",
          "vocabulary_id": "SNOMED",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "search_score": 90
        }
      ],
      "duration": 1034
    },
    {
      "search_id": "s3",
      "query": "aspirin",
      "status": "completed",
      "results": [
        {
          "concept_id": 1112807,
          "concept_name": "Aspirin",
          "concept_code": "1191",
          "vocabulary_id": "RxNorm",
          "domain_id": "Drug",
          "concept_class_id": "Ingredient",
          "standard_concept": "S",
          "search_score": 100
        }
      ],
      "duration": 957
    }
  ],
  "meta": {
    "request_id": "req_bulk_search_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

Usage Examples

Basic Bulk Search

Search multiple terms simultaneously without filters:

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {"search_id": "s1", "query": "diabetes"},
      {"search_id": "s2", "query": "hypertension"},
      {"search_id": "s3", "query": "asthma"}
    ]
  }'

Filtered Bulk Search with Defaults

Apply common filters to all searches using defaults, with per-search overrides:

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaults": {
      "vocabulary_ids": ["SNOMED"],
      "domain_ids": ["Condition"],
      "standard_concept": "S"
    },
    "searches": [
      {"search_id": "s1", "query": "diabetes"},
      {"search_id": "s2", "query": "heart failure"},
      {"search_id": "s3", "query": "metformin", "vocabulary_ids": ["RxNorm"], "domain_ids": ["Drug"]}
    ]
  }'

In this example, searches s1 and s2 use the defaults (SNOMED, Condition domain, standard concepts only). Search s3 overrides with RxNorm vocabulary and Drug domain. Apply different filters to each search individually:

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {"search_id": "s1", "query": "diabetes", "vocabulary_ids": ["SNOMED"], "domain_ids": ["Condition"]},
      {"search_id": "s2", "query": "metformin", "vocabulary_ids": ["RxNorm"], "domain_ids": ["Drug"]},
      {"search_id": "s3", "query": "HbA1c", "vocabulary_ids": ["LOINC"], "domain_ids": ["Measurement"]}
    ]
  }'

High-Volume Processing

Process larger batches from a file:

curl -X POST "https://api.omophub.com/v1/search/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @bulk_queries.json

Example bulk_queries.json:

{
  "defaults": {
    "vocabulary_ids": ["SNOMED"],
    "standard_concept": "S"
  },
  "searches": [
    {"search_id": "q1", "query": "diabetes mellitus"},
    {"search_id": "q2", "query": "essential hypertension"},
    {"search_id": "q3", "query": "chronic kidney disease"},
    {"search_id": "q4", "query": "atrial fibrillation"},
    {"search_id": "q5", "query": "congestive heart failure"}
  ]
}

Optimization Strategies

Query Grouping

Batch Size: Optimal batch size is 10-50 queries per request
Bulk Mode: The bulk_mode parameter (default true) enables optimized query execution for better throughput
Result Limit: Each query returns up to 20 results by default (configurable via page_size, max 100)

Performance Tips

Use concise, specific search terms for faster results
Split very large query sets into multiple requests of 50 queries each
Use the search_id field to correlate results with your source data
Use defaults to apply common filters instead of repeating them per search
Applying filters (vocabulary, domain) generally improves performance by narrowing the search space

Error Handling

Each query in the batch is processed independently
Failed queries return status: "failed" with an error message
Successful queries are not affected by failures in other queries

Basic Search - Single query search with pagination
Advanced Search - Complex search with advanced filters
Semantic Search - AI-powered contextual search

API Reference

Search

Concepts

Concept Hierarchy

Mappings

FHIR Resolver

Relationships

Domains & Classifications

Vocabularies

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Bulk Search

Filtered Bulk Search with Defaults

Per-Search Filters

High-Volume Processing

Optimization Strategies

Query Grouping

Performance Tips

Error Handling

​Overview

​Request Body

​Query Parameters

​Response

​Usage Examples

​Basic Bulk Search

​Filtered Bulk Search with Defaults

​Per-Search Filters

​High-Volume Processing

​Optimization Strategies

​Query Grouping

​Performance Tips

​Error Handling

​Related Endpoints

Overview

Request Body

Query Parameters

Response

Usage Examples

Basic Bulk Search

Filtered Bulk Search with Defaults

Per-Search Filters

High-Volume Processing

Optimization Strategies

Query Grouping

Performance Tips

Error Handling

Related Endpoints