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)
Provide required AOE inputs, when applicable
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 are not returned immediately after submission and become available only after laboratory processing completes.

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.