Skip to main content

​
Overview

Expands an implicit ValueSet to return a paginated list of matching codes. This powers dropdown menus, autocomplete, and template validation in EHRbase, HAPI FHIR, and other FHIR clients. OMOPHub supports implicit ValueSets defined by code system URIs — no stored ValueSet definitions required.

​
Supported Patterns

​
All codes from a code system

curl "https://fhir.omophub.com/fhir/r4/ValueSet/\$expand?\
url=http://snomed.info/sct?fhir_vs&count=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Descendants of a concept (is-a filter)

curl "https://fhir.omophub.com/fhir/r4/ValueSet/\$expand?\
url=http://snomed.info/sct?fhir_vs=isa/73211009&count=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
This expands to all descendants of “Diabetes mellitus” (73211009). This is the pattern EHRbase uses in template referenceSetUri: 
<referenceSetUri>terminology://fhir.omophub.com/fhir/r4/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=isa/73211009</referenceSetUri>

​
With text filter (typeahead/autocomplete)

curl "https://fhir.omophub.com/fhir/r4/ValueSet/\$expand?\
url=http://snomed.info/sct?fhir_vs&filter=diabet&count=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Parameters

ParameterTypeRequiredDescription
urluriYesImplicit ValueSet URL (e.g., http://snomed.info/sct?fhir_vs or http://snomed.info/sct?fhir_vs=isa/73211009)
filterstringNoText filter to match against concept display names
offsetintegerNoPaging start position (default: 0)
countintegerNoPage size (default: 100, max: 1000)

​
Response

{
  "resourceType": "ValueSet",
  "status": "active",
  "expansion": {
    "identifier": "urn:uuid:a1b2c3d4-...",
    "timestamp": "2026-04-12T10:00:00Z",
    "total": 247,
    "offset": 0,
    "parameter": [
      { "name": "offset", "valueInteger": 0 },
      { "name": "count", "valueInteger": 20 }
    ],
    "contains": [
      {
        "system": "http://snomed.info/sct",
        "code": "44054006",
        "display": "Type 2 diabetes mellitus"
      },
      {
        "system": "http://snomed.info/sct",
        "code": "46635009",
        "display": "Type 1 diabetes mellitus"
      }
    ]
  }
}

​
Pagination

Use offset and count to page through large expansions. The response includes total for the total number of matching concepts. 
# Page 2 (items 20-39)
curl "https://fhir.omophub.com/fhir/r4/ValueSet/\$expand?\
url=http://snomed.info/sct?fhir_vs=isa/73211009&offset=20&count=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Errors

HTTPIssue CodeCause
400invalidMissing url parameter, invalid ValueSet URL format, or unknown code system URI
403forbiddenRestricted vocabulary (CPT4)