Lab Example Workflow

The example workflow demonstrates a step-by-step process for laboratory ordering and result retrieval using FHIR R4.

Overview

Follow this sequence:

Submit a laboratory order
Add specimen details (optional)
Retrieve the order
Retrieve structured results
Retrieve document-based results
Subscribe to event notifications (optional)

All requests require OAuth 2.0 authentication and use application/fhir+json.

Submit an Order

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",
        "subject": {
          "reference": "Patient/12345"
        },
        "requester": {
          "reference": "Practitioner/67890"
        },
        "code": {
          "coding": [
            {
              "system": "https://example.healthgorilla.com/compendium/lab",
              "code": "005009",
              "display": "CBC with Differential"
            }
          ]
        }
      }
    }
  ]
}

Ensure that test codes are retrieved from the selected laboratory’s compendium and not reused across laboratories.

Example Response

{
  "resourceType": "RequestGroup",
  "id": "ord_78901",
  "status": "active",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2026-03-18T10:22:00Z"
  }
}

Store the RequestGroup.id to track and retrieve the order.

Add Specimen (Optional)

Include specimen data when required by the selected tests:

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": "2026-03-18T09:45:00Z"
  }
}

Reference the Specimen from the corresponding ServiceRequest when required.

Add Required Inputs

Some tests require additional inputs at order time (AOEs). These are submitted as a QuestionnaireResponse and referenced from ServiceRequest.supportingInfo.

{
  "resourceType": "QuestionnaireResponse",
  "status": "completed",
  "item": [
    {
      "linkId": "FASTING",
      "answer": [
        {
          "valueCoding": {
            "code": "Y",
            "display": "Yes"
          }
        }
      ]
    }
  ]
}

If required inputs are missing, the order will fail validation.

Retrieve the Order

GET /fhir/R4/RequestGroup/ord_78901
Authorization: Bearer {access_token}

Retrieve order status and metadata.

Retrieve Structured Results

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

Example Response

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "DiagnosticReport",
        "id": "dr_1122",
        "status": "final",
        "code": {
          "text": "CBC with Differential"
        },
        "subject": {
          "reference": "Patient/12345"
        },
        "result": [
          {
            "reference": "Observation/obs_3344"
          }
        ]
      }
    }
  ]
}

Results become available after laboratory processing and are not returned immediately after order submission.

Retrieve Observations

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

Retrieve discrete result values associated with the report.

Retrieve Document-Based Results

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

Download File

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

Retrieve the underlying report file.

Subscribe To Event Notifications (Optional)

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.example.com/webhook",
    "payload": "application/fhir+json"
  }
}

Receive notifications when results become available.

Key Notes

Results are delivered asynchronously after laboratory processing
Store the RequestGroup.id to track order status and results
Use based-on relationships to link results to orders
Handle OperationOutcome responses for validation and routing errors
Some tests may require additional inputs. Include all required data when submitting the order.

Summary

Follow this workflow to submit orders, track status, and retrieve results using Lab Network.

Combine these steps with the Order API and Lab Endpoints to implement a complete laboratory workflow.