Searching & Filtering

Most FHIR resources in the Health Gorilla API support search operations using query parameters. This allows clients to retrieve only the relevant subset of records for a specific patient or clinical context.

A FHIR search is typically performed using the pattern:
GET /[ResourceType]?[parameter]=[value]

For example, the query
GET /Observation?patient=123456&code=72166-2
returns observation records for patient 123456 where the LOINC code corresponds to “Body temperature”.

Required Parameter: patient

For nearly all clinical resources, the patient parameter is required to scope the query. This ensures data isolation and returns only those resources linked to the specified patient.

Common Parameter Types

Type	Description	Example
`token`	Coded values (status, code, category)	`status=active`
`reference`	Linked resource ID	`patient=Patient/12345`
`date`	Temporal filters on clinical events	`recordedDate=ge2023-01-01`
`string`	Text-based search on names or identifiers	`name=smith`
`quantity`	Numeric search values (used rarely)	`value-quantity=gt5.0`

Date Filtering

Date parameters support prefixes for range-based filtering:

Prefix	Meaning	Example
`eq`	Equal to	`birthdate=eq1980-01-01`
`ge`	Greater than or equal to	`recordedDate=ge2022-01-01`
`le`	Less than or equal to	`onset=le2023-12-31`

If no prefix is provided, FHIR treats the date as eq by default.

Multiple Values

To search for multiple values, use comma separation (a logical OR): GET /Condition?clinicalStatus=active,recurrence

To require all values (logical AND), repeat the parameter: GET /Condition?code=12345&code=67890

Modifier Support

Some parameters support modifiers that change how values are interpreted:

Modifier	Description	Example
`:exact`	Match value exactly	`name:exact=Smith`
`:contains`	Match substrings	`code:contains=lipid`
`:not`	Exclude a specific value	`clinicalStatus:not=resolved`

Not all modifiers are supported across all resource types.

Combining Parameters

All parameters in a query are combined using a logical AND, for example: GET /Observation?patient=12345&code=72166-2&date=e2023-01-01. This returns observations that match all three criteria.

Best Practices

Always include patient in patient-scoped queries
Use coded values (status, code, category) whenever possible
Use date ranges rather than exact dates to avoid missing records
Avoid overly broad queries — they may be paginated or rate-limited