Fullscript Labs Integration Guide

Overview

Lab recommendations originate within a treatment plan and, when purchased by a patient, become lab orders. These orders contain one or more lab tests, each of which can produce individual results.

Integrators must:

Create and activate a treatment plan with lab recommendations.
Monitor purchase and fulfillment via webhook events.
Retrieve lab results using the API.

Lab Order Lifecycle

The lab order progresses through several statuses:

Status	Description	Triggers lab_order.updated?
not_purchased	Lab recommended, but not purchased yet	❌
purchased	Patient has purchased the lab	❌ (*see order.placed)
schedule_appointment	The lab purchased requires an appointment to be scheduled	❌
upcoming_appointment	Appointment scheduled	❌
processing	Sample received and is being processed	❌
partial_results	Some but not all results available	✅
results_ready	All results available	✅
results_amended	Previously published results have been updated	✅
interpretation_ready	The results are ready to be interpreted in Fullscript	❌
interpretation_shared	Practitioner shared interpretation with patient	❌

Not all labs require appointments. schedule_appointment and upcoming_appointment only apply to labs that do.

Entities & Relationships

Treatment Plan – Includes one or more lab recommendations.
Lab Order – Created once the lab recommendation is purchased.
Lab Test – A component of the lab order; there may be multiple.
Lab Result – Associated with a test(s).

Mapping Tests and Results

The lab_order object contains two key arrays:

tests[]: Lists all tests ordered.
results[]: Lists results received, which may or may not directly align one-to-one with the tests.

Important Notes:

There might be no direct mapping between result entries and test entries.
This reflects how lab providers deliver data. Some group multiple tests into one result; others separate them.

Current Workaround:

If only one test exists in the lab order, label the result using the test name.
If multiple tests exist, fallback logic is recommended:
- Use the lab order name or
- Use the result ID as a filename.

API Reference

Retrieve All Lab Orders

GET /api/clinic/labs/orders

Returns a list of lab orders for the clinic.

Retrieve a Single Lab Order

GET /api/clinic/labs/orders/{id}

Returns detailed info on a lab order, including:

state
tests[]
results[]

Retrieve a Lab Test

GET /api/clinic/labs/tests/{id}

Returns metadata about an individual lab test.

Treatment Plan API (for creating Lab Recommendations)

Labs are added to treatment plans under the lab_recommendations array.

Once a draft treatment plan is created, you must activate it:

PATCH /api/clinic/treatment_plans/{treatment_plan_id}/activate

This will make the plan visible to the patient and enable lab purchase.

Webhooks

order.placed

Triggered when the patient purchases the lab.

{
  "type": "order.placed",
  "data": {
    "line_items": [
      {
        "variant_id": "...",
        "type": "labs" // Identify lab orders
      }
    ]
  }
}

Use this to detect lab purchases.

lab_order.updated

Triggered only when results become available or are amended. Does not trigger on purchase or appointment scheduling.

{
  "type": "lab_order.updated",
  "data": {
    "lab_order": {
      "id": "...",
      "status": "results_ready" | "partial_results" | "results_amended"
    }
  }
}

You must poll the API to track state changes like purchased, processing, and appointment statuses.