Search
K
< Back

Lab Endpoints

The Lab Network API exposes FHIR R4 endpoints that support electronic ordering, routing, and result retrieval across connected laboratories.

Use these endpoints to create and manage laboratory requisitions, submit specimens, retrieve results, and monitor order activity through event-based notifications.

FHIR Resources Used in Lab Ordering

The Lab Network API uses a set of standard FHIR resources to represent laboratory workflows. Each resource plays a specific role in the order and results lifecycle.

ResourcePurpose
RequestGroupRepresents the full laboratory requisition (order header).
ServiceRequestDefines individual tests or panels requested within the order.
SpecimenDescribes the collected sample, container, and collection details.
DiagnosticReportContains the structured lab report returned by the laboratory.
ObservationHolds discrete result values or analytes derived from the DiagnosticReport.
DocumentReference / BinaryProvides unstructured results such as PDFs or scanned images.
SubscriptionSends real-time notifications when orders or results are updated.
OperationOutcomeReturns validation or routing errors encountered during submission.

How the Endpoints Work Together

Each endpoint represents a stage in the laboratory workflow, used sequentially to submit, track, and retrieve lab orders and results.

  1. Submit a RequestGroup to create the overall requisition.
  2. Add ServiceRequests for each ordered test or panel.
  3. Attach a Specimen that identifies the collected sample.
  4. Monitor routing and status until the lab confirms receipt.
  5. Retrieve DiagnosticReports and associated Observations once results are ready.
  6. Access DocumentReferences and Binary resources for unstructured reports.
  7. Register a Subscription to receive event-driven notifications for order or result updates.

FHIR Resource Relationships

The following diagram illustrates how Lab Network resources relate to one another in a typical order lifecycle.

RequestGroup (Order Header)
├── ServiceRequest (Test / Panel)
│     └── Specimen (Collected Sample)
└── DiagnosticReport (Lab Report)
        ├── Observation (Discrete Results)
        └── DocumentReference (Unstructured Report)

Each downstream resource traces back to the originating RequestGroup, ensuring full data lineage and auditability.

Available Endpoints

ActionMethod & PathDescription
Submit an orderPOST /fhir/R4/RequestGroupCreates a new laboratory requisition that references one or more ServiceRequest resources.
Retrieve an orderGET /fhir/R4/RequestGroup/{id}Returns the complete order and associated ServiceRequest resources.
Update an orderPATCH /fhir/R4/RequestGroup/{id}Updates order metadata, notes, or references.
Add or modify a testPOST /fhir/R4/ServiceRequest
PATCH /fhir/R4/ServiceRequest/{id}		Adds a new test or updates parameters for an existing test.
Submit a specimenPOST /fhir/R4/SpecimenProvides specimen details and associates them with ServiceRequest resources.
Retrieve structured resultsGET /fhir/R4/DiagnosticReport?based-on=RequestGroup/{id}Returns structured reports for a submitted order.
Retrieve discrete observationsGET /fhir/R4/Observation?based-on=RequestGroup/{id}Retrieves analyte-level result data.
Retrieve documentsGET /fhir/R4/DocumentReference?subject=Patient/{pid}&category=laboratoryLists unstructured result documents for a patient.
Download report artifactGET /fhir/R4/Binary/{id}Retrieves the original PDF or image file referenced by a DocumentReference.
Subscribe to eventsPOST /fhir/R4/SubscriptionRegisters a webhook for order status or result notifications.

Each of these endpoints operates independently but forms part of a unified workflow that enables full control over laboratory data submission and retrieval.

Using the Endpoints

Use the endpoints sequentially to create a RequestGroup for the order, reference one or more ServiceRequest resources, and submit validated tests against the configured laboratory compendium. Health Gorilla applies routing rules to ensure only supported tests are transmitted.

When the lab completes testing, results are normalized and published as DiagnosticReport and Observation resources, with optional DocumentReference attachments for unstructured reports. Use Subscription to receive event-driven updates instead of polling.

All Lab Network API requests follow standard FHIR R4 conventions and require OAuth 2.0 authentication with application/fhir+json content type.