Skip to main content
GET
/
v1
/
concepts
curl -X GET "https://api.omophub.com/v1/concepts?query=diabetes&vocabulary_ids=SNOMED,ICD10CM&standard_concept=S" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "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",
      "standard_concept": "S",
      "valid_start_date": "1970-01-01",
      "valid_end_date": "2099-12-31",
      "invalid_reason": null,
      "relevance_score": 0.98,
      "synonyms": [
        "Type II diabetes mellitus",
        "Non-insulin dependent diabetes mellitus",
        "Adult onset diabetes mellitus",
        "Maturity onset diabetes"
      ]
    },
    {
      "concept_id": 192279,
      "concept_name": "Type 1 diabetes mellitus",
      "concept_code": "46635009",
      "vocabulary_id": "SNOMED",
      "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "valid_start_date": "1970-01-01",
      "valid_end_date": "2099-12-31",
      "invalid_reason": null,
      "relevance_score": 0.95,
      "synonyms": [
        "Type I diabetes mellitus",
        "Insulin dependent diabetes mellitus",
        "Juvenile onset diabetes mellitus"
      ]
    }
  ],
  "meta": {
    "request_id": "req_search_concepts_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "search_criteria": {
      "query": "diabetes",
      "vocabulary_ids": ["SNOMED", "ICD10CM"],
      "standard_concept": "S",
      "include_synonyms": true
    },
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 157,
      "total_pages": 8,
      "has_next": true,
      "has_previous": false
    },
    "vocab_release": "2025.2"
  }
}

​
Overview

The primary endpoint for searching medical concepts across all vocabularies. Supports text search, filtering by vocabulary, domain, concept class, and various other criteria.

​
Authentication

This API requires HTTPS and authentication via bearer token in the Authorization header. Include your API key in the following format: 
Authorization: Bearer YOUR_API_KEY
API keys can be obtained from your developer dashboard. Service API keys have broader access than user tokens. Tokens do not expire but can be revoked. Note that requests over plain HTTP are not supported.

​
Query Parameters

​
query
string
required
Search query text (concept name, synonym, or code)
​
vocabulary_ids
string
Comma-separated list of vocabulary IDs to search within
Examples: SNOMED, SNOMED,ICD10CM, LOINC,RXNORM
​
domain_ids
string
Comma-separated list of domain IDs to filter by
Examples: Condition, Procedure,Drug
​
concept_class_ids
string
Comma-separated list of concept class IDs to filter by
​
standard_concept
string
Filter by standard concept status
Options: S (standard), C (classification), N (non-standard)
​
include_synonyms
boolean
default:"true"
Include concept synonyms in search
​
include_relationships
boolean
default:"false"
Include concept relationships in response
​
include_invalid
boolean
default:"false"
Include invalid/deprecated concepts
​
min_score
number
default:"0.0"
Minimum relevance score (0.0 to 1.0)
​
exact_match
boolean
default:"false"
Require exact term matching
​
page
integer
default:"1"
Page number for pagination
​
page_size
integer
default:"20"
Number of concepts per page (max 100)
​
sort_by
string
default:"relevance"
Sort criteria
Options: relevance, concept_name, concept_code, vocabulary_id
​
sort_order
string
default:"desc"
Sort order
Options: asc, desc
​
vocab_release
string
Specific vocabulary release version

​
Response

​
success
boolean
Indicates if the request was successful
​
data
array
Array of concept objects matching the search criteria
​
meta
object
curl -X GET "https://api.omophub.com/v1/concepts?query=diabetes&vocabulary_ids=SNOMED,ICD10CM&standard_concept=S" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "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",
      "standard_concept": "S",
      "valid_start_date": "1970-01-01",
      "valid_end_date": "2099-12-31",
      "invalid_reason": null,
      "relevance_score": 0.98,
      "synonyms": [
        "Type II diabetes mellitus",
        "Non-insulin dependent diabetes mellitus",
        "Adult onset diabetes mellitus",
        "Maturity onset diabetes"
      ]
    },
    {
      "concept_id": 192279,
      "concept_name": "Type 1 diabetes mellitus",
      "concept_code": "46635009",
      "vocabulary_id": "SNOMED",
      "vocabulary_name": "Systematized Nomenclature of Medicine Clinical Terms",
      "domain_id": "Condition",
      "concept_class_id": "Clinical Finding",
      "standard_concept": "S",
      "valid_start_date": "1970-01-01",
      "valid_end_date": "2099-12-31",
      "invalid_reason": null,
      "relevance_score": 0.95,
      "synonyms": [
        "Type I diabetes mellitus",
        "Insulin dependent diabetes mellitus",
        "Juvenile onset diabetes mellitus"
      ]
    }
  ],
  "meta": {
    "request_id": "req_search_concepts_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "search_criteria": {
      "query": "diabetes",
      "vocabulary_ids": ["SNOMED", "ICD10CM"],
      "standard_concept": "S",
      "include_synonyms": true
    },
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 157,
      "total_pages": 8,
      "has_next": true,
      "has_previous": false
    },
    "vocab_release": "2025.2"
  }
}

​
Usage Examples

Search for diabetes concepts: 
curl -X GET "https://api.omophub.com/v1/concepts?query=diabetes" \
  -H "Authorization: Bearer YOUR_API_KEY"
Search within specific vocabularies and domains: 
curl -X GET "https://api.omophub.com/v1/concepts?query=hypertension&vocabulary_ids=SNOMED&domain_ids=Condition&standard_concept=S" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
High Relevance Results

Get only high-relevance results: 
curl -X GET "https://api.omophub.com/v1/concepts?query=myocardial%20infarction&min_score=0.8&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Include Relationships

Search with relationship data: 
curl -X GET "https://api.omophub.com/v1/concepts?query=diabetes&include_relationships=true&page_size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"