Introduction

​

Base URLs

https://api.omophub.com/v1

https://fhir.omophub.com/fhir/r4

​

Authentication

Authorization: Bearer oh_xxxxxxxxx

​

Core Capabilities

• Full-text search across 100+ medical vocabularies (SNOMED CT, ICD-10, LOINC, RxNorm, NDC, HCPCS, ATC, and more)
• Semantic search powered by neural embeddings - match by clinical meaning, not just keywords
• Autocomplete, fuzzy matching, phonetic search, and faceted filtering

• Standard FHIR operations: $lookup, $validate-code, $translate, $expand, $subsumes, $find-matches, $closure
• OMOP-specific operation: $diff for comparing concepts between vocabulary releases
• CodeSystem and ValueSet search-type queries for client discovery (HAPI, EHRbase)
• FHIR batch Bundles, per-vocabulary CodeSystem stubs, and R4 / R4B / R5 / R6 wire formats on the same endpoint

• One-call resolution: FHIR Coding or CodeableConcept → OMOP standard concept + domain + CDM target table
• Maps to traversal for non-standard codes, semantic fallback for display-text-only inputs
• Single, batch (up to 100 codings), and CodeableConcept variants with OHDSI vocabulary preference ranking

• Cross-vocabulary mapping between any OMOP vocabulary pair
• Mapping quality scores and coverage analysis
• Batch mapping: up to 100 concepts per request

• Traverse ancestor / descendant hierarchies with configurable depth and relationship-type filters
• Explore non-hierarchical relationships (Maps to, Has ingredient, RxNorm has dose form, etc.)
• Phoebe-powered concept recommendations for phenotype development

• Batch concept retrieval, relationship queries, hierarchy queries, and mappings (up to 100 per request)
• Bulk search and bulk semantic search for large ETL workloads
• Each batch / bulk request counts as one API call against your quota

• Synced with OHDSI ATHENA releases
• Version-specific API routing via X-Vocab-Release header or vocab_release query parameter

​

API Structure

• Resource-based endpoints (/concepts, /vocabularies, /search, /mappings, /fhir/resolve)
• Standard HTTP methods (GET, POST)
• Consistent JSON response envelope

• snake_case for all fields (concept_id, vocabulary_id, domain_id, target_concept_code)
• Consistent naming across REST API, SDK responses, and FHIR property codes

• Page-based: page (1-indexed) and page_size (default 20, max 1000) query parameters
• Response meta.pagination includes total_items, total_pages, page, page_size, has_next, has_previous

​

API Categories

​

Quick Start Examples

​

Search for Concepts

curl "https://api.omophub.com/v1/search/concepts?query=diabetes&vocabulary_ids=SNOMED&page_size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Semantic Search

curl "https://api.omophub.com/v1/concepts/semantic-search?query=chest+pain+that+gets+worse+when+breathing&page_size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Get Concept Details

curl "https://api.omophub.com/v1/concepts/201826" \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Map Between Vocabularies

curl "https://api.omophub.com/v1/concepts/201826/mappings?target_vocabularies=ICD10CM" \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Resolve a FHIR Code to OMOP

curl -X POST "https://api.omophub.com/v1/fhir/resolve" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system": "http://snomed.info/sct",
    "code": "44054006",
    "resource_type": "Condition"
  }'

​

FHIR $lookup

curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$lookup?system=http://snomed.info/sct&code=44054006" \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Response Format

{
  "success": true,
  "data": {
    // Response payload
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-14T10:30:00Z",
    "vocab_release": "2025.2"
  }
}

​

Response Codes

​

Rate Limits

​

Next Steps