Lab Example Workflow

The Lab Network API supports end-to-end electronic ordering and result retrieval through FHIR R4. The following examples demonstrate how to create, submit, and retrieve laboratory orders, attach specimens, and receive results through event-driven notifications.

All requests require OAuth 2.0 authentication and the application/fhir+json content type. Example values are for demonstration only and may differ from your tenant configuration or laboratory compendia.

Create a Laboratory Order

Create a RequestGroup resource to represent the order and include one or more referenced ServiceRequest resources for each test or panel. Each test code must come from the selected laboratory’s compendium.

To create a lab order

Send a POST request to /fhir/R4/RequestGroup.
Include patient and ordering provider references.
Add a ServiceRequest for each test in the order.

Example request:

POST /fhir/R4/RequestGroup
Content-Type: application/fhir+json
Authorization: Bearer {access_token}

{
  "resourceType": "RequestGroup",
  "status": "active",
  "intent": "order",
  "subject": { "reference": "Patient/12345" },
  "author": { "reference": "Practitioner/67890" },
  "action": [
    {
      "resource": {
        "resourceType": "ServiceRequest",
        "status": "active",
        "intent": "order",
        "code": {
          "coding": [
            {
              "system": "https://compendium.healthgorilla.com/labcorp",
              "code": "005009",
              "display": "CBC with Differential"
            }
          ]
        }
      }
    }
  ]
}

Example response:

{
  "resourceType": "RequestGroup",
  "id": "ord_78901",
  "status": "active",
  "intent": "order",
  "subject": { "reference": "Patient/12345" },
  "meta": { "versionId": "1", "lastUpdated": "2025-06-12T10:22:00Z" }
}

Add a Specimen

Add a Specimen resource that describes the collected sample, collection date, and container information. Each specimen must reference the same patient and be linked to the related ServiceRequest.

To create a specimen

Send a POST request to /fhir/R4/Specimen.
Include the specimen type and collection details.
Reference the patient and associate the specimen with the test.

Example request:

POST /fhir/R4/Specimen
Content-Type: application/fhir+json
Authorization: Bearer {access_token}

{
  "resourceType": "Specimen",
  "subject": { "reference": "Patient/12345" },
  "type": {
    "coding": [
      { "system": "http://terminology.hl7.org/CodeSystem/v2-0487", "code": "BLD", "display": "Blood" }
    ]
  },
  "collection": { "collectedDateTime": "2025-06-12T09:45:00Z" }
}

Example response:

{
  "resourceType": "Specimen",
  "id": "spec_9988",
  "status": "available",
  "subject": { "reference": "Patient/12345" }
}

Retrieve Diagnostic Reports

When the lab completes testing, it returns structured results as DiagnosticReport resources linked to the originating order.

To retrieve structured results

Send a GET request to /fhir/R4/DiagnosticReport.
Use the based-on parameter with the order’s RequestGroup ID.

Example request:

GET /fhir/R4/DiagnosticReport?based-on=RequestGroup/ord_78901
Authorization: Bearer {access_token}
Accept: application/fhir+json

Example response:

{
  "resourceType": "DiagnosticReport",
  "id": "dr_1122",
  "status": "final",
  "code": { "text": "CBC with Differential" },
  "subject": { "reference": "Patient/12345" },
  "result": [
    { "reference": "Observation/obs_3344" },
    { "reference": "Observation/obs_3345" }
  ],
  "effectiveDateTime": "2025-06-13T07:30:00Z"
}

Retrieve Observations

Each individual result value is represented as an Observation. Retrieve these using the same based-on parameter.

Example request:

GET /fhir/R4/Observation?based-on=RequestGroup/ord_78901
Authorization: Bearer {access_token}
Accept: application/fhir+json

Example response:

{
  "resourceType": "Observation",
  "id": "obs_3344",
  "code": { "text": "Hemoglobin" },
  "valueQuantity": { "value": 14.2, "unit": "g/dL" },
  "referenceRange": [
    { "low": { "value": 13.5 }, "high": { "value": 17.5 }, "unit": "g/dL" }
  ]
}

Retrieve Unstructured Reports

Some labs return reports as PDFs or image files. These are represented as DocumentReference resources with a linked Binary.

To retrieve a document

Query for documents by patient and category.
Use the Binary reference to download the file.

Example request:

GET /fhir/R4/DocumentReference?subject=Patient/12345&category=laboratory
Authorization: Bearer {access_token}
Accept: application/fhir+json

Example response:

{
  "resourceType": "DocumentReference",
  "id": "doc_2211",
  "status": "current",
  "type": { "text": "Lab Report" },
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "url": "https://api.healthgorilla.com/fhir/R4/Binary/bin_2211"
      }
    }
  ]
}

Example PDF download:

GET /fhir/R4/Binary/bin_2211
Authorization: Bearer {access_token}
Accept: application/pdf

To create a subscription

Send a POST request to /fhir/R4/Subscription.
Define the filter criteria and target webhook endpoint.

Example request:

POST /fhir/R4/Subscription
Content-Type: application/fhir+json
Authorization: Bearer {access_token}

{
  "resourceType": "Subscription",
  "status": "active",
  "criteria": "DiagnosticReport?status=final",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://client-system.example.com/fhir/notifications",
    "payload": "application/fhir+json"
  }
}

Notifications are sent as Parameters resources that reference the new DiagnosticReport and related patient or encounter.

Best Practices

Validate all test codes against the lab compendium before submission.
Use based-on relationships to maintain traceability between orders and results.
Subscribe for event-driven updates instead of polling.
Preserve Provenance data for audit and compliance.
Handle OperationOutcome responses for validation or routing errors.