Expand a ValueSet

$expand evaluates a ValueSet definition and returns an expanded ValueSet containing its included codes. Use it to build code pickers or inspect the concepts covered by a binding. The expansion is generated from the terminology content and versions available to the server, so treat it as a current result rather than a permanent copy.

Method	Path
GET or POST	/fhir/R4/ValueSet/$expand

GET request

Use query parameters for a ValueSet already known to the server. At the type-level endpoint, provide a url, context, or valueSet input. This example expands a registered ValueSet by canonical URL, filters it for a matching term, and asks for the first 20 concepts.

curl --get 'https://api.sandbox.ovok.com/fhir/R4/ValueSet/$expand' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode 'url=https://example.org/fhir/ValueSet/vitals' \
  --data-urlencode 'filter=heart' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'count=20'

filter is a text filter interpreted by the terminology server. offset and count request a page when the server supports paging for a flat expansion.

POST request

Use a FHIR Parameters body when supplying the ValueSet definition inline. The server may choose not to accept inline ValueSets; it must support the ValueSet or canonical URL otherwise.

curl --request POST \
  --url 'https://api.sandbox.ovok.com/fhir/R4/ValueSet/$expand' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/fhir+json' \
  --data @expand-valueset-parameters.json

Example expand-valueset-parameters.json:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "valueSet",
      "resource": {
        "resourceType": "ValueSet",
        "status": "active",
        "compose": {
          "include": [
            {
              "system": "http://loinc.org",
              "concept": [
                { "code": "8867-4", "display": "Heart rate" }
              ]
            }
          ]
        }
      }
    }
  ]
}

Successful response

The response is the expanded ValueSet itself, not a Parameters wrapper.

Response path	Example	Meaning
resourceType	ValueSet	Identifies the returned FHIR resource.
status	active	Status of the ValueSet.
expansion.identifier	urn:uuid:<expansion-id>	Identifier for this generated expansion.
expansion.timestamp	<ISO-8601 timestamp>	Time at which the expansion was produced.
expansion.total	1	Total number of matching concepts.
expansion.offset	0	Starting position when paging is used.
expansion.contains[]	http://loinc.org / 8867-4 / Heart rate	Expanded concepts, with their code system, code, display, and possibly designations or other properties.

An oversized expansion may return an OperationOutcome instead. Use offset and count for supported flat expansions rather than requesting an unbounded result.

Reference: HL7 FHIR R4 ValueSet $expand.