Bulk Search: Granular Filter Parameters & Defaults
Bulk search now supports per-query and default-level filters for vocabulary, domain, concept class, standard concept status, and more.
The POST /v1/search/bulk endpoint now supports granular filtering on each search item, plus a defaults object that applies shared filters across all queries in a single request. Previously, bulk search only accepted query and search_id per item. Now you have full control over how each query is scoped.
New Filter Parameters
Each search item in the searches array accepts the following optional filters:
| Parameter | Type | Description |
|---|---|---|
vocabulary_ids | string[] | Restrict results to specific vocabularies (e.g., ["SNOMED", "ICD10CM"]) |
domain_ids | string[] | Filter by domain (e.g., ["Condition", "Drug"]) |
concept_class_ids | string[] | Filter by concept class (e.g., ["Clinical Finding"]) |
standard_concept | string | Filter by standard concept status (S, C, or null) |
include_invalid | boolean | Include invalid concepts in results (default: false) |
page_size | number | Number of results per query (default: 20, max: 1000) |
Defaults Object
Set shared filters once via the top-level defaults object. Individual search items inherit these values and can override any of them:
{
"defaults": {
"vocabulary_ids": ["SNOMED"],
"standard_concept": "S",
"page_size": 10
},
"searches": [
{ "query": "diabetes", "search_id": "q1" },
{ "query": "aspirin", "search_id": "q2", "vocabulary_ids": ["RxNorm"] }
]
}
In this example, q1 searches SNOMED standard concepts, while q2 overrides vocabulary_ids to search RxNorm instead.
Example Request
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", "ICD10CM"],
"domain_ids": ["Condition"],
"standard_concept": "S",
"include_invalid": false,
"page_size": 5
},
"searches": [
{ "query": "type 2 diabetes", "search_id": "diabetes" },
{ "query": "essential hypertension", "search_id": "htn" },
{ "query": "E11", "search_id": "icd_code", "vocabulary_ids": ["ICD10CM"], "standard_concept": null }
]
}'
Concept Code Search Improvements
Searching by concept code (e.g., E11, J45) now works reliably in bulk search. The search path includes concept code prefix matching, so partial codes return the expected results without requiring an exact match.