Date Filtering

Two different kinds of time appear in the Health Gorilla FHIR API, and choosing between them is the decision date filtering exists to settle. The clinical event date describes when care happened. The modification timestamp describes when a resource arrived or changed in the FHIR server. A patient can have a 2019 encounter that reached Health Gorilla last week, so the two answers are often nothing alike.

Filtering on the right one keeps responses smaller, keeps longitudinal records accurate, and keeps incremental synchronization from re-fetching data your system already holds.

Two Kinds of Date

Every temporal parameter belongs to one of two families.

date and _lastUpdated are search parameters and work on standard resource searches. start, end, and _since are parameters of the $everything operation. For their formats, defaults, and the rest of that operation's parameters, go to Everything.

The bounds don't all behave the same way. On DiagnosticReport, Encounter, and Observation, date is inclusive, as are _lastUpdated, start, and end, so a record dated exactly on a bound is returned. DocumentReference is the exception, described below. _since is exclusive, so a resource whose meta.lastUpdated matches the supplied timestamp exactly is left out, and a resource carrying no modification timestamp at all is left out too. Every comparison is made in Coordinated Universal Time (UTC). When you store the timestamp of a completed retrieval and pass it back as _since, that boundary behavior is what keeps you from receiving the same resources twice.

If start falls after end, the request fails with HTTP 400 and the message Start date must be before end date.

The Patient360 operations $p360-search and $p360-retrieve take their own startDate and endDate parameters instead of the parameters described here. Go to each operation's own page for those.

Which Filter to Use

Choose the clinical family when the question is about the patient's care timeline:

• Building a longitudinal record for a defined care period
• Limiting a chart or export to the last two years of care
• Answering a clinical question scoped to when treatment occurred

Choose the modification family when the question is about your own synchronization state:

• Retrieving only what changed since your last successful pull
• Reconciling after an outage or a failed webhook delivery
• Polling for updates, which is described in Polling

A resource can satisfy one filter and fail the other, so the two aren't interchangeable, and combining them narrows a result set rather than widening it.

Clinical Date Fields

The date search parameter isn't available on every resource. Four resource types support it, and the element each one compares against differs.

Encounter comparisons use Encounter.period.start, so an encounter is matched on when it began rather than on the whole span it covers. A long encounter that started before your range and continued into it isn't returned.

DocumentReference is the exception in the table, in two ways.

First, DocumentReference.date records when the document reference was created, not the period of care the document describes, so a document about a 2019 admission carries the date it was filed. Treat it as document metadata rather than a clinical event date.

Second, its bounds behave differently depending on where the document came from. For documents already stored in Health Gorilla, both bounds are exclusive: a document created exactly on the date you supply is not returned. For documents retrieved on demand from a network, the bounds are inclusive and compared at day precision. So the same query can include or exclude a document sitting exactly on a boundary, depending on its source. Set the range one day wider than you need if a boundary document matters.

Date Values per Request

DiagnosticReport, Encounter, and Observation accept one date value per request. Sending two, such as a lower bound and an upper bound together, returns HTTP 400. To bound both ends of a range on those resources, either supply one bound with date and narrow the other side in your own system, or use the $everything operation, where start and end are designed to work as a pair.

DocumentReference accepts two date values, so a two-sided range works there.

Resources Without Dates

Other clinical resources, including Condition, Procedure, Immunization, AllergyIntolerance, and MedicationRequest, don't support clinical date filtering, and sending date to one of them returns HTTP 400. To narrow results for those resources, filter on _lastUpdated, or apply the date filter in your own system after retrieval.

A record that carries no value in the compared date element is excluded from a date-filtered search. No error is returned, so a record missing its effective date simply won't appear in a date-filtered result even though it exists. The same applies to _lastUpdated and to _since on $everything. If completeness matters more than the date window, retrieve without the filter and narrow afterwards.

Resources with no clinical date element, such as Patient and Organization, aren't narrowed by start and end in an $everything response. They're returned whatever range you supply, which keeps the clinical records that reference them interpretable. A standard resource search returns only the resource type you requested.

Timestamp Format

Clinical date parameters accept a year, a year and month, or a full date: 2024, 2024-03, or 2024-03-15. A partial value is treated as the range it covers, so date=eq2024 matches the whole of 2024 and date=ge2024-03 starts at 1 March. Comparisons are made against the boundaries of that range, which is why date=gt2024-03-15 starts after the end of that day rather than at midnight.

Clinical date parameters use an International Organization for Standardization (ISO) 8601 date, YYYY-MM-DD. Modification timestamps use an ISO 8601 date and time with a Z suffix for UTC, YYYY-MM-DDThh:mm:ssZ. The Z keeps interpretation unambiguous across time zones.

meta.lastUpdated on every returned resource reports when that resource was last written:

"meta": {
  "lastUpdated": "2025-02-12T14:23:57Z"
}

That timestamp reports when the resource was last written in the Health Gorilla FHIR server, which can differ from when the source system last changed the record. A change in the timestamp doesn't on its own mean the clinical content changed.

Your system should convert timestamps to a local time zone for storage or display rather than assuming the API returns local time.

Examples

Retrieve observations for care that occurred on or after a date:

GET /fhir/R4/Observation?patient=12345&date=ge2024-01-01

Retrieve document references for a single calendar year. DocumentReference is the one resource that accepts two date values:

GET /fhir/R4/DocumentReference?patient=12345&date=ge2023-01-01&date=le2023-12-31

Retrieve resources written to the FHIR server on or after a timestamp, regardless of when the care occurred:

GET /fhir/R4/Observation?patient=12345&_lastUpdated=ge2025-02-01T00:00:00Z

Retrieve everything for a patient from a given clinical date forward:

GET /fhir/R4/Patient/12345/$everything?start=2023-01-01

Retrieve everything for a patient that changed in the FHIR server after your last successful retrieval:

GET /fhir/R4/Patient/12345/$everything?_since=2025-02-01T00:00:00Z

Combine both families in one request, asking for observations describing care from 2024 onward that also reached the FHIR server after February 1, 2025:

GET /fhir/R4/Observation?patient=12345&date=ge2024-01-01&_lastUpdated=ge2025-02-01T00:00:00Z&_count=50

The following pair shows the two families answering different questions about the same patient. The first returns encounters that reached the FHIR server after February 1, 2025, including care delivered years earlier. The second returns encounters for care delivered on or after February 1, 2025, however long ago they were written.

GET /fhir/R4/Encounter?patient=12345&_lastUpdated=ge2025-02-01T00:00:00Z
GET /fhir/R4/Encounter?patient=12345&date=ge2025-02-01

Best Practices

The following guidelines help you apply the clinical and modification families correctly:

• Use the clinical family, date, start, and end, for anything a clinician would recognize as a care timeline.
• Confirm the resource supports date before relying on it. Only DiagnosticReport, DocumentReference, Encounter, and Observation accept it.
• Send one date value per request on DiagnosticReport, Encounter, and Observation. Only DocumentReference accepts two.
• Use the modification family, _lastUpdated and _since, for incremental synchronization, and store the timestamp of your last successful retrieval.
• Use ranges rather than exact dates so records with imprecise or partial dates aren't missed.
• Include patient when you're scoping to one patient. Most clinical resource searches require it, though DiagnosticReport and DocumentReference accept it as optional.
• Pair a temporal filter with the other parameters the resource supports to narrow large result sets further.
• Page through large result sets by following the supplied next link, as described in Pagination.