Lab Network API

The Lab Network API provides programmatic access to laboratory ordering and result retrieval.

Use the API to submit diagnostic orders, track order status, and retrieve results using FHIR R4 resources. The API is the only access model that supports structured result retrieval and downstream data integration.

Core Workflow

Laboratory orders are validated against laboratory requirements and processed asynchronously after submission. Results become available after laboratory processing completes.

A typical workflow includes:

1. Submit an order using RequestGroup and ServiceRequest
2. Validate the order against the selected laboratory’s compendium and requirements
3. Route the order to a laboratory that supports the requested tests
4. Process the order at the laboratory
5. Confirm submission status
6. Retrieve results using FHIR APIs

Implementation

A typical API implementation includes:

• Submitting laboratory orders using FHIR R4 resources
• Handling asynchronous submission and tracking order status
• Retrieving structured and document-based results
• Optionally receiving event notifications for order status and results

All workflows should be validated in a non-production environment before moving to production.

Submit an Order

Orders are submitted as FHIR RequestGroup resources containing one or more ServiceRequest resources.

Example Payload

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

Compendium Alignment

Before submitting orders, your system must align with the selected laboratory’s compendium.

This includes:

• Mapping your internal test catalog to lab-specific test codes
• Ensuring required order fields and metadata are included
• Providing required inputs for tests that require additional data
• Confirming that requested tests are valid and orderable

Orders that do not match the compendium are rejected during validation. This is the most common cause of order submission failures.

Important: Lab-specific test codes should be retrieved from the selected laboratory’s compendium rather than reused across laboratories.

Specimen Handling (When Required)

If your workflow requires specimen data:

• Create a Specimen resource with collection details
• Reference the specimen from the corresponding ServiceRequest
• Ensure consistency between specimen, patient, and order context

Proper specimen handling supports traceability and correct laboratory processing.

Example Specimen Payload

{
  "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"
  }
}

Submission Status

Order submission is not always immediate. After submission, Lab Network performs validation and routing, and may process the request asynchronously.

When asynchronous processing is used:

1. Submit the order using POST /fhir/R4/RequestGroup
2. Read the Location header in the response
3. Poll the RequestResult endpoint
4. Use the response to determine whether the order was accepted, rejected, or requires further action.

POST /fhir/R4/RequestGroup

Response Header

Location: /fhir/R4/RequestResult/{id}

Follow-up Request

GET /fhir/R4/RequestResult/{id}

RequestResult represents the outcome after validation and routing and should be used to confirm whether the order was accepted, rejected, or partially processed.

Retrieve Results

Results are not available immediately after order submission. Laboratories must complete processing before results are returned.

Structured Results

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

Document-Based Results

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

When to retrieve results:

• After receiving a notification via Subscription, or
• After confirming that the order has completed or results are available

Subscription Setup (Optional)

Lab Network supports event-driven workflows using FHIR Subscription.

Subscriptions are commonly used to receive:

• Order status updates (RequestGroup)
• Result availability (DiagnosticReport)

To configure subscriptions:

1. Expose a secure HTTPS endpoint to receive notifications
2. Create one or more Subscription resources
3. Validate that your endpoint can receive and process notifications

Subscriptions allow your system to receive updates without polling.

Example Subscription Payload

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

Requirements

Your system must support:

• FHIR R4 APIs
• Secure HTTPS communication
• JSON-based request and response handling

Your system must be able to create, retrieve, and process the following FHIR resources:

• RequestGroup
• ServiceRequest
• DiagnosticReport
• Observation
• DocumentReference
• Binary
• OperationOutcome

The following resources are used when applicable:

• Specimen for workflows requiring specimen details
• Subscription for event-driven notifications

Your system should also:

• Store order identifiers for tracking and reconciliation
• Link results back to originating orders
• Handle asynchronous result delivery

Authentication

Lab Network uses OAuth 2.0 for API authentication. All API requests must include a valid access token in the Authorization header.

Your system must be configured with the appropriate scopes for:

• Order submission
• Result retrieval
• Subscription management (if using subscriptions)

Scope configuration is provided during onboarding.

Environment Configuration

Lab Network provides separate environments for testing and production use.

You must:

• Use the sandbox environment for implementation and validation
• Use the production environment for live workflows

Each environment has:

• Separate base URLs
• Separate credentials
• Independent configuration

Validate all workflows in the sandbox environment before moving to production.

Operational Requirements

Your system must support ordering workflows in production.

This includes:

• Registering ordering providers and organizations
• Ensuring accurate patient demographic data
• Defining processes for handling validation errors and rejected orders
• Monitoring order status and result delivery

Your system should be able to:

• Investigate failed or delayed orders
• Reconcile results with originating orders
• Handle exceptions in downstream workflows

Results are delivered asynchronously and must be retrieved after laboratory processing completes or via subscription notifications.

Go-Live Checklist

Before submitting production orders, confirm the following:

• Authentication is configured and working
• API requests succeed in the sandbox environment
• Test codes are correctly mapped to the lab compendium
• Required inputs are provided where applicable
• Order submission and retrieval workflows are validated
• Result retrieval is functioning correctly
• Subscriptions are configured and tested (if used)
• OperationOutcome handling is implemented
• Providers and organizations are configured

Summary

API implementation enables your system to submit laboratory orders, retrieve results, and operate within Lab Network workflows.

Successful implementation requires alignment across:

• Technical capabilities
• Laboratory compendium configuration
• Operational readiness

These steps ensure accurate order processing, reliable result delivery, and stable production performance.