Skip to main content
Spec reference: https://hl7.org/fhir/search.html
FHIR search is how clients query sets of resources using standardized query parameters. The result is always a Bundle of type searchset.

​
What you get back

Search responses are Bundle resources with type: "searchset". Each match appears in Bundle.entry[].resource. Servers may also include additional entries with entry.search.mode = "include" when you request _include or _revinclude.

​
Where search lives

FHIR defines three common scopes for search:
ScopeWhat you searchExample
Type-levelOne resource typeGET /fhir/Patient?name=Doe
System-levelMultiple typesGET /fhir/_search?_type=Patient,Observation
CompartmentResources related to one compartment instanceGET /fhir/Patient/123/Observation
When you want to know “what does this server support?”, request the server’s CapabilityStatement and inspect its supported search parameters per resource type.

​
Search parameter semantics

​
AND vs OR

FHIR uses two different “grouping” rules:
  • Different parameters are AND: gender=male&active=true
  • Repeating the same parameter is AND: name=John&name=Smith
  • Comma-separated values are OR: name=John,Smith
This means you can express “(John OR Smith) AND active” like this: 
GET /fhir/Patient?name=John,Smith&active=true

​
Presence testing (:missing)

Most parameter types support checking whether an element is present: 
GET /fhir/Patient?email:missing=true
GET /fhir/Patient?birthdate:missing=false

​
Common search parameter types

FHIR SearchParameters have a declared type. The same parameter name can behave very differently depending on its type.
TypeExampleNotes
stringname=DoeText matching; often supports modifiers like :contains and :exact
token`identifier=http://acme.example/mrn123`“System | code” matching (also used for code, status, tags, etc.)
referencesubject=Patient/123Matches a reference; supports chaining on many servers
datebirthdate=ge1990-01-01Supports prefixes like ge, le, gt, lt
numbervalue=gt5Numeric prefixes like gt, lt, ge, le
quantity`value-quantity=5http://unitsofmeasure.orgmg`Value + optional unit system and code
uriurl=http://example.orgURI matching semantics (often exact)
Which parameters exist for a resource type is defined by SearchParameter resources and the FHIR specification for that type (e.g., Patient search parameters differ from Observation).

​
Modifiers and prefixes

​
String modifiers

Common string modifiers: 
GET /fhir/Patient?name:exact=John Doe
GET /fhir/Patient?name:contains=jo

​
Date / number prefixes

Common comparison prefixes: 
GET /fhir/Observation?date=ge2024-01-01
GET /fhir/Observation?date=lt2025-01-01
GET /fhir/Observation?value-quantity=gt5
Ranges are typically expressed by repeating the parameter: 
GET /fhir/Observation?date=ge2024-01-01&date=le2024-12-31

​
Result parameters (how the response is shaped)

These parameters don’t filter “which resources match” — they control the bundle you get back:
  • _count: page size (number of matches per response)
  • _sort: ordering of results
  • _total: whether to include total count (none, estimate, accurate)
  • _summary: return less data (true, text, data, count)
  • _elements: return only certain top-level elements
  • _include / _revinclude: also return related resources
_summary and _elements are about payload size. Servers can implement them differently; treat them as performance hints, not correctness requirements.

​
Pagination

FHIR pagination is server-controlled: the server returns Bundle.link URLs (e.g. next), and clients should follow those URLs rather than constructing their own paging logic. At minimum you should expect a self link, and possibly next, prev, first, and last.

​
POST-based search (_search)

Search parameters can be sent via POST as form-urlencoded data (useful when URLs get long): 
POST /fhir/Patient/_search
Content-Type: application/x-www-form-urlencoded

name=Doe&gender=male&_count=10

​
Try it

1

Search a type (no filters)

curl -H "Accept: application/fhir+json" \
  "http://localhost:8080/fhir/Patient?_count=5"
2

Add one filter

curl -H "Accept: application/fhir+json" \
  "http://localhost:8080/fhir/Patient?name=Doe&_count=5"
3

Let the server tell you what’s supported

The CapabilityStatement lists supported search parameters per type:
curl -H "Accept: application/fhir+json" \
  "http://localhost:8080/fhir/metadata"

​
Next steps

Search (TLQ FHIR)

TLQ FHIR-specific behavior, paging, and limits

Type-Level Search API

Endpoint reference + examples

System-Level Search API

Search across multiple resource types

Compartment Search API

Search “everything related to X”