Skip to main content
The OMOPHub API supports multiple vocabulary release versions through a sophisticated schema-based versioning system. Each release contains the complete OHDSI vocabulary data for that time period, ensuring data consistency and enabling time-based analysis.

​
Current Available Releases

The following vocabulary releases are currently available in the system:
VersionRelease DateFHIR CodeSystem IDStatusDefaultRelease Notes
2026.12026-02-27omop-v20260227ActiveYesLink
2025.22025-08-27omop-v20250827ActiveNoLink
2025.12025-02-27omop-v20250227ActiveNoLink
2024.22024-08-30omop-v20240830ActiveNoLink
The FHIR CodeSystem ID column is what you pass to the FHIR Terminology Service for release-pinned instance reads and operations - e.g. GET /fhir/r4/CodeSystem/omop-v20250827 or CodeSystem/omop-v20250827/$lookup?.... FHIR handlers accept both formats interchangeably: the OMOPHub version (2025.2) and the FHIR ID (omop-v20250827). The FHIR ID is computed deterministically from the release date (omop-v + YYYYMMDD).

​
FHIR Code System URIs

Each vocabulary release is served through both the REST API (by OMOP vocabulary_id) and the FHIR Terminology Service at https://fhir.omophub.com/fhir/{r4,r4b,r5,r6}/ (by canonical FHIR system URI). The mapping below is stable across releases - only the underlying concepts change between versions.
FHIR System URIOMOP vocabulary_id
http://snomed.info/sctSNOMED
http://loinc.orgLOINC
http://www.nlm.nih.gov/research/umls/rxnormRxNorm
http://hl7.org/fhir/sid/icd-10ICD10
http://hl7.org/fhir/sid/icd-10-cmICD10CM
http://hl7.org/fhir/sid/icd-10-pcsICD10PCS
http://hl7.org/fhir/sid/icd-10-cnICD10CN
http://hl7.org/fhir/sid/icd-10-gmICD10GM
http://hl7.org/fhir/sid/icd-9-cmICD9CM
http://hl7.org/fhir/sid/icd-9ICD9Proc
http://hl7.org/fhir/sid/icd-9-cnICD9ProcCN
http://hl7.org/fhir/sid/icd-o-3ICDO3
http://hl7.org/fhir/sid/cvxCVX
http://hl7.org/fhir/sid/ndcNDC
http://www.nlm.nih.gov/research/umls/hcpcsHCPCS
http://www.whocc.no/atcATC
http://unitsofmeasure.orgUCUM
urn:iso:std:iso:11073:10101MDC
http://fdasis.nlm.nih.govUNII
http://va.gov/terminology/medrtMED-RT
https://fhir-terminology.ohdsi.orgOMOP unified omnibus
Source of truth is apps/api/src/config/fhir-vocabularies.ts. To get the live list from the running service, call GET /fhir/r4/metadata?mode=terminology - the TerminologyCapabilities resource enumerates every supported codeSystem.uri.

​
Version Abbreviations

For convenience, the API supports several abbreviations for version specification:
AbbreviationMaps ToDescription
latest2026.1Always points to the most recent release
default2026.1Same as latest - the system default
current2026.1Alias for the default version
2026v12026.1Half-based abbreviation
2025v22025.2Half-based abbreviation
2025v12025.1Half-based abbreviation
2024v22024.2Half-based abbreviation

​
How to Select Vocabulary Versions

You can specify which vocabulary version to use in your API requests using any of these methods: Add the vocab_release parameter to any API endpoint: 
# Using specific version
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024.1" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Using abbreviation
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024v1" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Using latest (default behavior)
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=latest" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Method 2: HTTP Header

Use the X-Vocab-Release header: 
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Vocab-Release: 2024.2"

​
Default Version Behavior

When no version is specified:
  • Default Version: 2025.2
  • Fallback: If the default version is unavailable, the system uses the latest available active version
  • Caching: Responses are cached with version-specific keys to ensure consistency

​
Version Comparison Example

Here’s how to compare concept availability across versions: 
import requests

def compare_concept_across_versions(concept_code, vocabulary_id):
    """Compare a concept across different vocabulary versions."""
    headers = {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
    
    versions = ['2025.2', '2025.1', '2024.2']
    results = {}
    
    for version in versions:
        response = requests.get(
            'https://api.omophub.com/v1/concepts/search',
            headers=headers,
            params={
                'query': concept_code,
                'vocabulary_ids': vocabulary_id,
                'vocab_release': version,
                'page_size': 1
            }
        )
        
        data = response.json()
        if data.get('data'):
            concept = data['data'][0]
            results[version] = {
                'found': True,
                'concept_name': concept['concept_name'],
                'standard_concept': concept.get('standard_concept'),
                'valid_start_date': concept.get('valid_start_date'),
                'valid_end_date': concept.get('valid_end_date')
            }
        else:
            results[version] = {'found': False}
    
    return results

# Example usage
concept_comparison = compare_concept_across_versions('E11.9', 'ICD10CM')
for version, info in concept_comparison.items():
    if info['found']:
        print(f"Version {version}: {info['concept_name']}")
    else:
        print(f"Version {version}: Not found")

​
Version-Specific Features

​
Temporal Queries

Query concepts as they existed at specific points in time: 
# Get diabetes concepts as they existed in 2024v2
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024.2" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Historical Analysis

Compare vocabulary evolution over time: 
# Compare concept relationships across versions
curl -X GET "https://api.omophub.com/v1/concepts/123456/relationships?vocab_release=2024.2" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Migration Support

Validate concept mappings when upgrading between versions: 
# Validate proposed mappings against OMOP standards
curl -X POST "https://api.omophub.com/v1/mappings/validate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mappings":[{"source_concept_id":201826,"target_concept_id":1569178005,"mapping_type":"Maps to"}]}'

​
Version Support Policy

​
Active Versions

  • Current + 2 previous releases are actively supported

​
Deprecated Versions

  • Removal notice provided 90 days before discontinuation

​
Troubleshooting

​
Common Issues

​
Version Not Found

{
  "error": "VOCABULARY_VERSION_NOT_FOUND",
  "message": "Vocabulary version '2023.1' is not available",
  "available_versions": ["2026.1", "2025.2", "2025.1", "2024.2"]
}
Solution: Use the /v1/vocabularies/releases endpoint to check available versions.

​
Version Mismatch in Results

If you receive unexpected results, verify the version is being applied correctly: 
# Check which version was actually used
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024.2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -v  # Verbose mode shows response headers
Look for the X-Vocab-Release-Used header in the response to confirm the version.

​
FAQ

The system automatically uses the default version (2026.1). This provides the most recent vocabulary data and optimal performance through caching.
No, each API request operates against a single vocabulary version. To compare across versions, make separate requests for each version.
Major vocabulary updates typically occur twice a year (February and August), following the OHDSI vocabulary release cycles.