Order API

The Order API enables submission and tracking of laboratory orders using FHIR R4 resources within Lab Network.

Orders are processed through a structured set of FHIR resources that capture patient context, requested tests, and related clinical and operational metadata.

The API supports the full order lifecycle, from submission through result delivery and reconciliation.

Overview

Laboratory orders are represented using a combination of FHIR R4 resources:

• RequestGroup: the overall order container
• ServiceRequest: individual tests or panels within the order

Each order contains:

• Patient identity and demographics
• Ordering practitioner and organization
• Requested tests aligned to the laboratory compendium
• Clinical context and supporting information
• Order status, timestamps, and routing metadata

Each order is uniquely identifiable and can be retrieved and tracked throughout its lifecycle.

Resource Model

The resource model defines how laboratory orders are represented in FHIR and how related data is structured. Understanding this model is essential for constructing valid orders and ensuring that all required clinical, operational, and billing information is included.

RequestGroup

RequestGroup represents the complete laboratory order.

• Groups one or more ServiceRequest resources
• Provides overall order context
• Serves as the primary identifier for order tracking

ServiceRequest

ServiceRequest represents an individual test or panel within the order.

• Defines the requested diagnostic service
• Includes test codes aligned to the lab compendium
• References the patient, requester, and supporting context

Some tests require additional inputs provided as supporting data. These inputs must be included when required or the order will be rejected.

Supporting Resources

Additional resources may be included or referenced:

• Patient: patient identity and demographics
• Practitioner: ordering provider
• Organization: ordering facility
• Specimen: collection details (when required)

Supported Operations

Supported operations define how your system interacts with Lab Network through the FHIR API. These operations allow you to submit orders, track their status, and retrieve results as they become available.

Submit Order

POST /fhir/R4/RequestGroup

Creates a new laboratory order containing one or more ServiceRequest resources. Order submission may be processed asynchronously. Use the Location header and RequestResult endpoint to confirm submission outcome.

Example Order Payload

{
  "resourceType": "RequestGroup",
  "status": "active",
  "intent": "order",
  "subject": {
    "reference": "Patient/12345"
  },
  "author": {
    "reference": "Practitioner/67890"
  },
  "action": [
    {
      "resource": {
        "reference": "#test1"
      }
    }
  ],
  "contained": [
    {
      "resourceType": "ServiceRequest",
      "id": "test1",
      "status": "active",
      "intent": "order",
      "code": {
        "coding": [
          {
            "code": "005009",
            "display": "CBC with Differential"
          }
        ]
      },
      "subject": {
        "reference": "Patient/12345"
      }
    }
  ]
}

Retrieve Order

GET /fhir/R4/RequestGroup/{id}

Returns the current state of the order, including status and associated resources.

Search Orders

GET /fhir/R4/RequestGroup?patient={patient-id}

Retrieves orders associated with a specific patient.

Retrieve Structured Results

GET /fhir/R4/DiagnosticReport?based-on=RequestGroup/{order-id}
GET /fhir/R4/Observation?based-on=RequestGroup/{order-id}

Returns structured results linked to the originating order.

Retrieve Document-Based Results

GET /fhir/R4/DocumentReference?subject=Patient/{patient-id}&category=laboratory
GET /fhir/R4/Binary/{id}

Retrieves result documents and associated file content.

Key Fields

Important fields within RequestGroup and ServiceRequest include:

• subject: reference to the patient
• requester: ordering practitioner
• performer: performing laboratory (if specified)
• identifier: unique order identifier
• status: current state of the order
• code: test codes from the lab compendium
• reasonCode or reasonReference: clinical justification
• supportingInfo: related clinical context

All fields must conform to FHIR R4 and use appropriate coding systems where applicable.

Order Lifecycle

Orders progress through a lifecycle reflected in resource status.

Common states include:

• active: order submitted and in progress
• completed: results available
• cancelled: order not fulfilled

Additional internal processing steps such as validation and routing occur before fulfillment. Order status can be retrieved via API or monitored through subscriptions.

Result Linking

Results are linked to the originating order using FHIR relationships.

Key linkages include:

• DiagnosticReport.basedOn: references the originating RequestGroup
• DiagnosticReport.result: references associated Observation resources
• Observation.basedOn: references the originating RequestGroup
• DocumentReference.subject: references the patient associated with the result

These relationships allow systems to:

• Associate results with the original order
• Track fulfillment status
• Reconcile pending and completed orders

Supporting Inputs (AOE)

Some tests require Ask at Order (AOE) responses. These are submitted as QuestionnaireResponse resources and referenced from ServiceRequest.supportingInfo.

Before submitting an order, retrieve required AOE questions for the selected test using the Questionnaire endpoint.

GET /fhir/R4/Questionnaire?code={compendium-system}|{test-code}

Example Request

GET /fhir/R4/Questionnaire?code=urn:uuid:lab-compendium-id|005009

Example Response

{
  "resourceType": "Questionnaire",
  "item": [
    {
      "linkId": "FASTING",
      "text": "Has the patient been fasting?",
      "type": "choice",
      "answerOption": [
        {
          "valueCoding": {
            "code": "Y",
            "display": "Yes"
          }
        },
        {
          "valueCoding": {
            "code": "N",
            "display": "No"
          }
        }
      ]
    }
  ]
}

Provide responses using a QuestionnaireResponse resource and include it in ServiceRequest.supportingInfo. Missing or invalid AOE responses will cause order validation to fail.

Error Handling

Errors are returned using the FHIR OperationOutcome resource.

Common scenarios include:

• Invalid or missing required fields
• Compendium mismatches
• Unsupported test codes
• Routing or configuration issues

Your system should parse and handle OperationOutcome responses as part of normal workflow processing.

Example Error Response

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Missing required field: performer"
    }
  ]
}