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:

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.

Labs Catalog API

Browse available lab tests before creating a treatment plan. The catalog requires the catalog:read OAuth scope (or API keys) and is only available when labs ordering is enabled for the clinic.

• List lab tests — Returns a paginated catalog of active lab tests. Use the id from each entry as lab_test_id when creating treatment plans.
• Retrieve a lab test — Returns availability, product information (including HTML descriptions), and add-on tests for a single catalog entry.

See the Lab test catalog entry object reference for response fields, sample payloads, and error responses.

Lab Orders API

Retrieve All Lab Orders

GET /api/clinic/labs/orders
Copy

Returns a list of lab orders for the clinic.

Retrieve a Single Lab Order

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

Returns detailed info on a lab order, including:

• state
• tests[]
• results[]

Retrieve a Lab Test

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

Returns metadata about an individual lab test.

Treatment Plan API (for creating Lab Recommendations)

Create lab recommendations via Create a patient treatment plan.

Required OAuth scopes: clinic:write and labs:treatment_plans:create

Include a labs array with one or more tests from the labs catalog. Either recommendations or labs must be provided. Set lab_test_id to the variant UUID returned by the catalog API.

Activation options:

• Set send_to_patient: true to activate the plan and send it to the patient in one step
• Set state: "draft" to create a draft plan, then activate it later

When the request includes labs, the response includes checkout_url, lab_checkout_status, and patient_lab_fields_needed so the patient can complete lab checkout. See the treatment plan object and create endpoint reference for request and response samples, checkout field details, and error responses.

Webhooks

order.placed

Triggered when the patient purchases the lab.

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

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": "all_results_received" | "results_received" | "results_amended"
    }
  }
}
Copy

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