> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FHIR ValueSet search for OMOP concept sets

> Discover whether a FHIR ValueSet is supported by OMOPHub before calling $expand or $validate-code - catalog lookup for common clinical value sets.

## Overview

Search-type query on `ValueSet`. FHIR clients - notably HAPI FHIR's `RemoteTerminologyServiceValidationSupport` and EHRbase's `FhirTerminologyValidation` - call this endpoint as a preflight check: "does this server support the ValueSet I'm about to query?". If the returned `searchset` Bundle contains a matching entry, the client proceeds to [$expand](/api-reference/fhir-terminology/expand) or [ValueSet/$validate-code](/api-reference/fhir-terminology/valueset-validate-code). If the Bundle is empty, the client skips OMOPHub entirely for that ValueSet.

OMOPHub recognizes the same implicit ValueSet URL patterns that `$expand` handles - no stored ValueSet definitions required.

## Request

```bash theme={null}
curl "https://fhir.omophub.com/fhir/r4/ValueSet?\
url=http://snomed.info/sct?fhir_vs=isa/73211009" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Parameters

| Parameter | Type | Required | Description                                                                                                                                |
| --------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `url`     | uri  | No       | Implicit ValueSet URL to check support for. Omit to request an empty Bundle (OMOPHub does not enumerate every possible implicit ValueSet). |

### Supported URL patterns

| Pattern                       | Meaning                                         |
| ----------------------------- | ----------------------------------------------- |
| `{system}?fhir_vs`            | All concepts from a code system                 |
| `{system}?fhir_vs=isa/{code}` | Descendants of a specific concept (is-a filter) |

Where `{system}` is any of the [supported FHIR system URIs](/api-reference/fhir-terminology/overview#supported-vocabularies), and `{code}` is a code within that system.

## Response (supported)

```json theme={null}
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://fhir.omophub.com/fhir/r4/ValueSet/http---snomed-info-sct-fhir-vs-isa-73211009",
      "resource": {
        "resourceType": "ValueSet",
        "id": "http---snomed-info-sct-fhir-vs-isa-73211009",
        "url": "http://snomed.info/sct?fhir_vs=isa/73211009",
        "status": "active",
        "experimental": false,
        "name": "OMOPHub implicit ValueSet: http://snomed.info/sct?fhir_vs=isa/73211009",
        "description": "Implicit ValueSet backed by the OMOPHub FHIR Terminology Service. Call $expand on this ValueSet to enumerate its members."
      }
    }
  ]
}
```

The returned resource is a metadata stub. It does **not** include the expansion - callers must invoke [\$expand](/api-reference/fhir-terminology/expand) to enumerate members.

## Response (unknown URL)

```json theme={null}
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0
}
```

An empty Bundle (not a 404) is the FHIR convention for "no matches".

## Double percent-encoding tolerance

Spring-based clients (HAPI, EHRbase) sometimes encode the `url` parameter twice - once for the template or code (`terminology://fhir.hl7.org/ValueSet?url=http%3A%2F%2F...`) and again when building the outbound HTTP request. OMOPHub detects the second encoding layer automatically and decodes it before parsing the implicit URL. Single-encoded URLs work too.

## Errors

Only malformed requests return errors - unknown URLs are handled via the empty-Bundle response.

| HTTP | Issue Code | Cause                      |
| ---- | ---------- | -------------------------- |
| 401  | `login`    | Missing or invalid API key |

## See Also

* [ValueSet/\$expand](/api-reference/fhir-terminology/expand) - enumerate the members of a supported ValueSet
* [ValueSet/\$validate-code](/api-reference/fhir-terminology/valueset-validate-code) - check membership for a specific code
* [EHRbase / openEHR Integration](/guides/integration/ehrbase-openehr) - walkthrough of the full composition-validation flow that drives this endpoint