Displaying Orders and Results

The iFrame's job ends at submission. The order list, order history, reorder, and result review are accessed in your system. Each is built from what you retrieve through the API, including:

• The ordering provider, destination laboratory, and ordered tests
• The Lab Reference ID and accession number users need to track the order
• Structured results and the rendered result document
• The requisition as a PDF

Retrieving Orders

Orders are retrieved from the RequestGroup resource.

GET /fhir/R4/RequestGroup?_lastUpdated=gt2026-08-01T00:00:00Z

The query works across the tenant and does not require a patient parameter. A tenant-wide query can return more orders than a single response carries. Follow the next link to page through them. _count sets the page size and defaults to 20.

Writing the Query

Two parameters carry the filtering: status and _lastUpdated.

Values for status are Health Gorilla order-status tokens: draft, scheduled, submitted, failed, pending, sent, collected, completed, cancelled, and rescheduled. A submission failure is failed rather than submitFailed. FHIR statuses are rejected, so status=active returns "Status is not valid."

Filter dates with a full timestamp and a time zone. With a date-only value, the whole of the named day is excluded.

What the Response Carries

The RequestGroup carries the order-level information: ordering provider, destination laboratory, laboratory account, Health Gorilla order identifier, and Lab Reference ID. Its subject is a reference to the patient, and that reference carries the Health Gorilla patient identifier your system sends on later iFrame launches. The identifier is not in the launch response or callback.

Each ordered test appears as an action on the RequestGroup, with its resource referencing a ServiceRequest rather than carrying the test detail itself. Per-test fields such as the test code, priority, notes, and Ask at Order Entry answers live on those ServiceRequest resources. Follow the references to build a full order view.

A referenced ServiceRequest is retrieved with its own read, since _include is not supported on a RequestGroup search. Panels hold several tests each, so displaying a list of orders can mean a large number of requests.

Result retrieval is different. _include is supported on a DiagnosticReport search, so you can pull the report and its Observation resources together.

Polling and the Callback

Poll for order status rather than depending on the callback alone. A callback can be interrupted, or a browser session can close before the redirect completes, while the order itself reached the laboratory. Without a poll, your users see a failure that didn't happen.

Identifiers and Order Status

After submission, users follow an order through two identifiers and its status. Each comes from a different source and is needed at a different point.

Retrieving Results

Results reach your system through the FHIR APIs. A laboratory transmits results to Health Gorilla as HL7, and Health Gorilla matches each one to its original order by the order number the laboratory returns, scoped to your tenant and the ordering facility. The provider and patient are resolved from that order, and the result is then available to retrieve.

A completed result carries the laboratory, the date received, the Lab Reference ID, the accession number, the ordering provider, and every result value with its reference range and abnormal flags.

GET /fhir/R4/DiagnosticReport?patient={patientId}&status=final
GET /fhir/R4/DiagnosticReport/{reportId}/$pdf
GET /fhir/R4/Observation?patient={patientId}&category=laboratory

A laboratory can issue a corrected result later. The correction usually keeps the same report ID, so re-read the report rather than relying on a stored copy.

Which Resource to Use

Different resources carry different views of the same result, including one that depends on how the laboratory sent it:

• DiagnosticReport for the report-level view, or with the $pdf operation for the rendered document
• Observation for discrete result values
• DocumentReference with its content in a Binary, when a laboratory returns a result as a document rather than as discrete data

Subscriptions and Polling

Results are routed to your tenant and retrieved from there through the FHIR API. Notification that a result has arrived is a separate, optional layer.

If your organization has FHIR Subscriptions enabled, create a Subscription on DiagnosticReport to be notified as results arrive. Refer to Lab Network API for the setup steps and the client settings required for a subscription.

Confirm with Health Gorilla whether your agreement includes Subscriptions. Otherwise, poll for new results, which with many tenants means one query per tenant per interval.

When a Result Is Ready

Results are ready when the DiagnosticReport status is final. Order status is not a readiness signal, because completed is set as soon as the first result is linked, whether that result is preliminary, final, or corrected. Every ordering surface behaves this way, not only the iFrame, and the rule is stated in full on Ordering and Results.

If users report missing results, check the DiagnosticReport status before raising a delivery failure.

Display Options

Two routes are available to view results:

• Display the result PDF, which is the rendered document as the laboratory issued it, and cannot be filed into structured fields or trended
• Build a results screen in your system from the structured data

Clients who would rather build nothing can embed the Health Gorilla web app instead, through the separate integration described in ​Embedded iFrame.

Retrieving the Requisition

Patients going to a draw site need the requisition as a printed document. It is retrieved in two calls: the $pdf operation on RequestGroup returns a download link, generating the PDF if the order doesn't already have one, and a request to that link returns the document. Both calls are documented on Order API.

GET /fhir/R4/RequestGroup/{id}/$pdf