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 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

An order carries the hg-order profile. RequestGroup has no core element for the performing laboratory, the requester, or the billing account, so Health Gorilla adds each one as an extension.

The tests and the billing account are carried inside the order as contained resources. A contained resource is embedded in its parent rather than stored separately on the server, and it's referenced with # followed by its local id: a ServiceRequest with "id": "test1" under contained is referenced as "reference": "#test1" from action. The billing account is referenced from the account extension the same way.

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

Each ServiceRequest carries a category of SNOMED 103693007, Diagnostic procedure.

Additional inputs are required for some tests, provided as supporting data. Without them, the order is rejected.

Supporting Resources

Additional resources may be included or referenced:

Patient: patient identity and demographics
Practitioner: ordering provider
Organization: ordering facility
Account: billing account for the order
Specimen: collection details (when required)

Supported Operations

Supported operations define how your system interacts with Lab Network through the FHIR API. With these operations, you 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 is asynchronous, and asynchronous mode is required rather than optional: a synchronous request is refused with 400 and an OperationOutcome carrying the code async-required. The response carries a Location header holding the identifier to poll for the outcome.

Confirm Submission Outcome

GET /fhir/R4/RequestResult/{id}

Returns the outcome of an asynchronous submission, where {id} is taken from the Location header of the submission response. While the submission is still queued it returns 202. Once it completes it returns 200 with the submission response. An identifier that has expired or was never issued returns 454.

Submit a Draft Order

POST /fhir/R4/RequestGroup/{id}/$submit

Submits an order that was created with a status of draft. An order created with a status of active is submitted on creation, so this operation isn't required.

A draft order must carry the requestgroup-timing extension with a future execution date. Creating an order with a status of draft and no timing is rejected with 422 and the message "Timing required.", so a draft is a scheduled future order rather than a way to defer submission of an ordinary one.

Example Order Payload

{
  "resourceType": "RequestGroup",
  "meta": {
    "profile": [
      "https://healthgorilla.com/fhir/StructureDefinition/hg-order"
    ]
  },
  "status": "active",
  "intent": "order",
  "subject": {
    "reference": "Patient/12345"
  },
  "author": {
    "reference": "Practitioner/67890"
  },
  "contained": [
    {
      "resourceType": "ServiceRequest",
      "id": "test1",
      "status": "active",
      "intent": "order",
      "category": [
        {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "103693007",
              "display": "Diagnostic procedure"
            }
          ]
        }
      ],
      "code": {
        "coding": [
          {
            "code": "005009",
            "display": "CBC with Differential"
          }
        ]
      },
      "subject": {
        "reference": "Patient/12345"
      }
    },
    {
      "resourceType": "Account",
      "id": "account1",
      "meta": {
        "profile": [
          "https://healthgorilla.com/fhir/StructureDefinition/hg-order-account"
        ]
      },
      "type": {
        "coding": [
          {
            "system": "https://www.healthgorilla.com/order-billto",
            "code": "self",
            "display": "Client (Our Account)"
          }
        ]
      }
    }
  ],
  "extension": [
    {
      "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-account",
      "valueReference": {
        "reference": "#account1"
      }
    },
    {
      "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-performer",
      "valueReference": {
        "reference": "Organization/f-d36f565d2060a4b3bb4f4c8e"
      }
    },
    {
      "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-requester",
      "extension": [
        {
          "url": "agent",
          "valueReference": {
            "reference": "Practitioner/67890"
          }
        },
        {
          "url": "onBehalfOf",
          "valueReference": {
            "reference": "Organization/12345"
          }
        }
      ]
    }
  ],
  "action": [
    {
      "resource": {
        "reference": "#test1"
      }
    }
  ]
}

An order is rejected with 422 if any of the following is missing: the hg-order profile, status, intent, author, subject, the requester extension, the performer extension, the account extension with a contained Account carrying the hg-order-account profile and a type, or an action whose contained ServiceRequest carries a category, a status, an intent of order, and a code. The missing field is named in the OperationOutcome.

status accepts draft or active. intent accepts order.

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}
GET /fhir/R4/RequestGroup?identifier={order-identifier}

Retrieves orders associated with a specific patient, or a single order by its identifier. A patient search also accepts status and _lastUpdated.

Retrieve Structured Results

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

Returns the structured results linked to the originating order. Each DiagnosticReport references its discrete result values through DiagnosticReport.result, so follow those references to retrieve the Observation resources for the order.

Retrieve Document-Based Results

GET /fhir/R4/DocumentReference?patient=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
author: a core RequestGroup element, and required
requester: ordering practitioner, carried as an extension
performer: performing laboratory, carried as an extension and required
account: billing account, carried as an extension and required
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

Several lifecycle states share one ServiceRequest.status.

FHIR Status	Lifecycle States	Meaning
`draft`	Draft, Scheduled	Created but not submitted, or scheduled for a future execution date.
`on-hold`	Pending	Validated and queued for transmission to the performing laboratory. A system-managed queuing state, not a manual hold.
`active`	Submitted, Sent, Collected	Submitted to the performing laboratory, with no way to tell the three states apart from the FHIR status alone.
`completed`	Completed	Results are available.
`revoked`	Cancelled, Submission failed	Not fulfilled, or in the Submission failed state.
`unknown`	Rescheduled	Moved to a different execution date. FHIR has no status for this, so `unknown` carries it. This is a deliberate Health Gorilla use of the code rather than the value set's documented meaning: `unknown` is returned only for a rescheduled order, never to mean that an order's status is indeterminate.

A failed submission is reported as revoked only from REST API version 09-01-2026. On earlier versions it's reported as on-hold, the same code as a queued order, so the two can't be told apart. Go to User Identity & API Versioning to check which version your integration uses.

An order submitted through the $submit operation is tracked as a RequestGroup. Two statuses are reported differently from ServiceRequest: a rescheduled order is reported as draft rather than unknown, and a failed submission is reported as revoked on every REST API version.

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

With these relationships, your system can:

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

From REST API version 06-01-2025, a result can only be linked to an order for the same patient. A request that links a result and an order for different patients is refused with 422 and a business-rule OperationOutcome, whether the PATCH adds the link at /requestgroup-diagnosticReport on RequestGroup or at /basedOn on DiagnosticReport. It isn't enforced on earlier versions. An integration that doesn't request a version explicitly uses your client's configured default if one is set, or the platform default otherwise, either of which can be earlier than 06-01-2025. Confirm which version you target.

Only new link attempts are checked. Existing links stay as they are, and unlinking isn't affected.

Supporting Inputs (AOE)

Some tests require Ask at Order Entry (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=urn:uuid:f:{performer-facility-id}|{test-code}

The code system is built from the performing laboratory's facility identifier, the same Organization identifier carried in the order's performer extension. A compendium scoped to one practice takes the form urn:uuid:f:{performer-facility-id}:t:{tenant-id}.

Example Request

GET /fhir/R4/Questionnaire?code=urn:uuid:f:d36f565d2060a4b3bb4f4c8e|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. An order with missing or invalid AOE responses doesn't pass validation.

Each item in the Questionnaire carries a linkId holding the AOE question code, the same value carried in item.code. Key each answer in your QuestionnaireResponse to that linkId.

In Health Gorilla's Questionnaire, item.id carries the same value as linkId, so an integration already keyed to item.id resolves to the same key. Key new work to linkId: FHIR defines it for this purpose, it's mandatory on Questionnaire.item, and a resource whose items omit it doesn't pass strict validation.

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": "No performer supplied"
    }
  ]
}