Guides
  1. Guides
  2. Lab Network

Lab Network API

API implementation requires your system to meet a set of technical, configuration, and operational requirements to support laboratory ordering and result retrieval through Lab Network.

API-based access provides programmatic control over laboratory ordering, status tracking, and result retrieval using FHIR R4 resources. Use API access when your system needs structured results for downstream processing, analytics, or clinical workflows.

Overview

A typical API implementation includes:

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

Validate all functionality in a non-production environment before moving to production.

Minimum Required Workflow

A minimal API implementation supports the following:

  • Submit an order using RequestGroup and one or more ServiceRequest resources
  • Provide required inputs for tests that require additional data
  • Retrieve results using DiagnosticReport and Observation
  • Handle validation and processing errors using OperationOutcome

Additional capabilities such as document retrieval and event subscriptions may be added based on workflow needs.

A minimal order payload includes a RequestGroup, one or more ServiceRequest resources, patient and practitioner references, performer information, and billing configuration.

ExampleRequestGroup 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"
      }
    }
  ]
}

Asynchronous Submission

Order submission may be processed asynchronously depending on configuration and laboratory behavior.

When asynchronous processing is used:

  • Submit the order using POST /fhir/R4/RequestGroup
  • Read the Location header in the response
  • Poll the returned RequestResult endpoint
  • Use the RequestResult response to determine success, warning, or failure
POST /fhir/R4/RequestGroup

Response Header

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

Follow-up Request

GET /fhir/R4/RequestResult/{id}

RequestResult should be treated as the source of truth for submission outcome.

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

Before calling Lab Network APIs, your application must obtain an access token and include it in all requests.

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.

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

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

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 are not immediately available after order submission.

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.

Updated about 17 hours ago