Treatment Plans

API OVERVIEW

Pagination

Request IDs

Versioning

Rate Limits

Idempotency

Restricted endpoints

Going to production

CLINIC

Clinic

Retrieve a clinic

Staff

List all staff

Create a staff member

Retrieve a staff member

Update a staff member

Practitioners

List all practitioners

Create a practitioner

Retrieve a practitioner

Update a practitioner

Practitioner Types

List all practitioner types

Protocols

List all Fullscript protocols

List all practitioner protocols

Retrieve a protocol

Templates

List all practitioner templates

Retrieve a template

Labs

List all lab orders

Retrieve a lab order

Retrieve a lab test

List lab tests

Retrieve a lab test

Search for lab tests

Resources

List all practitioner resources

Create a resource

Retrieve a practitioner's resource

Update a resource

Delete a resource

List All Fullscript Resources

Metadata

Find objects

PATIENTS

Patients

List all dependents

List all patients

Create a patient

Retrieve a patient

Update a patient

Search for patients

Address

List All Patient Addresses

Orders

List all orders

Retrieve an Order

List all patient orders

Treatment Plans

Activate a treatment plan

Cancel a treatment plan

List all patient treatment plans

Create a patient treatment plan

Retrieve a treatment plan

Update a treatment plan

Create an in-office checkout

Dynamic link

Create a Draft Treatment Plan Link with Patient Matching UI

Retrieve a new Treatment Plan link

Create a Draft Treatment Plan Link

Retrieve a Treatment Plan Link

FULLSCRIPT CATALOG

Products

List all products

Retrieve a product

List similar products

The treatment plan object is the way for practitioners create prescriptions in Fullscript. The API allows you to create treatment plans. It also allows you to list all treatment plans that belong to a patient and find individual treatment plans.

Activate a treatment plan

This endpoint is restricted in production

You can explore these docs and call this endpoint freely in sandbox. Production access requires commercial approval — talk to your Fullscript integration contact, or see Restricted endpoints and going to production for what to expect.

Activates a draft Treatment Plan for a patient.

Arguments

treatment_plan_id

string

Required

Unique ID for the Treatment plan.

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

curl -X 'PATCH' "https://api-us-snd.fullscript.io/api/clinic/treatment_plans/{treatment_plan_id}/activate" \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

404

Not Found

422

Unprocessable Entity

Cancel a treatment plan

Cancels an active Treatment Plan for a patient.

Arguments

treatment_plan_id

string

Required

Unique ID for the Treatment plan.

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

curl -X 'PATCH' "https://api-us-snd.fullscript.io/api/clinic/treatment_plans/{treatment_plan_id}/cancel" \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

404

Not Found

422

Unprocessable Entity

List all patient treatment plans

This resource allows you to list all of a patient's treatment plans.

Arguments

patient_id

string

Required

Unique ID for the Patient

sort_by

string

Accepts one of the following arguments: created_at or updated_at.

order_by

string

Ordering defaults to ASC and can take an argument of ASC or DESC.

GET /api/clinic/patients/{patient_id}/treatment_plans

curl "https://api-us-snd.fullscript.io/api/clinic/patients/{patient_id}/treatment_plans" \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

404

Not Found

Create a patient treatment plan

This endpoint is restricted in production

Creates a new Treatment Plan for a patient.

Provide recommendations for supplement plans, labs for lab orders, or both. At least one of recommendations or labs is required.

Idempotency: This endpoint supports the Idempotency-Key header. See Idempotency for details.

Labs authentication: When using a bearer token, the labs:treatment_plans:create OAuth scope is required in addition to clinic:write. API keys may also create lab treatment plans when labs are enabled for the clinic.

Lab checkout: When the request includes labs, a successful 201 response includes checkout_url, practitioner_pay_url (unless the labs have already been purchased), lab_checkout_status, and patient_lab_fields_needed. Missing patient checkout fields (for example, date_of_birth or labs_tos) do not cause an error—the patient supplies them at checkout.

Error responses for lab requests

403 — OAuth token is missing the labs:treatment_plans:create scope (Doorkeeper scope error).
422 — Labs treatment plan ordering is not enabled for the clinic. Returns { "error": "Labs treatment plan ordering is not enabled for this clinic" }.
422 — Lab validation failed. Returns a structured body:

{ "error": "validation_failed", "message": "...", "details": [{ "field": "...", "code": "..." }] }

Common details[].code values for lab requests:

labs_not_enabled on field labs — Labs are not enabled for the clinic.
invalid_lab_test_id on field labs[n].lab_test_id — The lab test UUID was not found.
inactive_test on field labs[n].lab_test_id — The lab test exists but is no longer available.
practitioner_not_eligible_for_labs on field practitioner_id — The practitioner cannot order labs.
labs_onboarding_incomplete on field practitioner_id — The practitioner has not completed labs onboarding.
invalid_sample_collection on field labs[n].sample_collection — sample_collection is not one of the allowed values.

Additional plain 422 errors:

In-office phlebotomy is not enabled for this clinic — when using sample_collection: "in_office_phlebotomy" without the required clinic feature.
Practitioner sample collection selection is not enabled for this clinic — when using sample_collection: "practitioner_sample_collection" without the required clinic feature.

When neither recommendations nor labs are provided, the API returns { "error": "Unable to create a treatment plan without any recommendations" }.

Arguments

patient_id

string

Required

Unique ID for the Patient.

practitioner_id

string

Unique practitioner ID. Required if the current access token's resource owner type is Staff or Clinic. Otherwise defaults to the practitioner who owns the token, but can be specified to create the plan on behalf of a different practitioner.

personal_message

string

A personal message that a practitioner can attach to the treatment plan.

state

string

The state of the treatment plan. Takes an option of draft or active. Defaults to active if null. The value draft allows to create a draft treatment plan. The value active or null creates an active treatment plan.

recommendations

array

Rx plan for a product. Required unless labs are provided.

variant_id

string

Required

Unique ID for the Variant.

units_to_purchase

string

Required

Quantity (number of units) of variant to recommend.

refill

string

Send refill reminders?

take_with

string

What the product should be taken with. This can be any of the following strings: empty stomach, food, or water.

dosage

object

Dosage information for the recommendation.

amount

string

The dose to take. Expects numbers but can include a range or a fraction (e.g. 1, or 1-2, or 1/2 are all valid).

frequency

string

The frequency with which to take the dose. This can be any of the following strings: once per day, twice per day, three times per day, four times per day, every morning, or every night.

duration

string

The period for which to take the dose. This can be the number of days (e.g. 120 for 4 months) or it can be any of the following strings: as needed, until symptoms resolve, or ongoing.

additional_info

string

Extra instructions for taking dose (e.g. With meals).

format

string

Format of the recommended dose. This can be any of the following strings: capsule, chewable, gel, liquid, lozenge, packet, pellet, drops, powder, strip, suppository, or tablet.

time_of_day

array

The time(s) of day at which to take the dose. This can be any combination of the following strings: upon waking, morning, afternoon, evening, and bedtime.

metadata

object

Metadata to be attached to the treatment_plan.

id

string

Your system's unique treatment_plan identifier.

partner_order_id

string

Your system's unique order identifier. Stored as treatment plan metadata.

send_to_patient

boolean

When true, activates the treatment plan and sends it to the patient. Required for lab checkout when creating lab-only or mixed plans.

skip_email_notification

boolean

When true, suppresses the patient email notification when activating the treatment plan.

note

string

Optional personal message attached to the treatment plan.

labs

array

Lab tests to add to the treatment plan. Required unless recommendations are provided.

lab_test_id

string

Required

Lab test variant UUID from the labs catalog API.

quantity

string

Reserved for future use. Must be 1 in V1.

instructions

string

Instructions for the patient.

requires_fasting

string

Whether fasting is required.

sample_collection

string

Sample collection option. One of patient_chooses, in_office_phlebotomy, or practitioner_sample_collection.

sample_collection_provider_id

string

UUID of the sample collection provider. When omitted, the lab company's default provider is used.

expected_collection_date

string

Expected sample collection date (ISO 8601).

POST /api/clinic/patients/{patient_id}/treatment_plans

curl -X 'POST' "https://api-us-snd.fullscript.io/api/clinic/patients/{patient_id}/treatment_plans" \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
        -d $'{
  "practitioner_id": "string",
  "personal_message": "string",
  "state": "string",
  "recommendations": [
    {
      "variant_id": "string",
      "units_to_purchase": "string",
      "refill": "string",
      "take_with": "string",
      "dosage": {
        "amount": "string",
        "frequency": "string",
        "duration": "string",
        "additional_info": "string",
        "format": "string",
        "time_of_day": "array"
      }
    }
  ],
  "metadata": {
    "id": "string"
  },
  "partner_order_id": "string",
  "send_to_patient": "boolean",
  "skip_email_notification": "boolean",
  "note": "string",
  "labs": [
    {
      "lab_test_id": "string",
      "quantity": "string",
      "instructions": "string",
      "requires_fasting": "string",
      "sample_collection": "string",
      "sample_collection_provider_id": "string",
      "expected_collection_date": "string"
    }
  ]
}'

Responses

201

Created

403

Forbidden

422

Unprocessable Entity

Retrieve a treatment plan

Retrieves an existing treatment plan. You need to supply the unique ID for the treatment plan.

Arguments

id

string

Required

Unique ID for the Treatment Plan

GET /api/clinic/treatment_plans/{id}

curl "https://api-us-snd.fullscript.io/api/clinic/treatment_plans/{id}" \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

404

Not Found

Update a treatment plan

Updates a Treatment Plan for a patient.

Provide recommendations for supplement updates, labs for lab order updates, or both. At least one of recommendations, labs, or resource_ids is required.

Labs authentication: When using a bearer token, the labs:treatment_plans:create OAuth scope is required in addition to clinic:write when the request includes labs. API keys may also update lab treatment plans when labs are enabled for the clinic.

Lab checkout: When the request includes labs, a successful response includes checkout_url, lab_checkout_status, and patient_lab_fields_needed.

When labs is provided, existing lab recommendations on the treatment plan are replaced with the supplied list (same upsert semantics as recommendations).

You may also send lab_recommendations instead of labs. This accepts the same input fields as labs, or the response shape returned by GET/POST (including nested tests[].id variant UUIDs). If lab_recommendations is present but cannot be parsed into lab tests, existing labs are left unchanged.

Arguments

id

string

Required

Unique ID for the Treatment plan.

personal_message

string

A personal message that a practitioner can attach to the treatment plan.

recommendations

array

Rx plan for a product.

variant_id

string

Required

Unique ID for the Variant.

units_to_purchase

string

Required

Quantity (number of units) of variant to recommend.

refill

string

Send refill reminders?

take_with

string

What the product should be taken with. This can be any of the following strings: empty stomach, food, or water.

dosage

object

Dosage information for the for the recommednation.

amount

string

The dose to take. Expects numbers but can include a range or a fraction (e.g. 1, or 1-2, or 1/2 are all valid).

frequency

string

The frequency with which to take the dose. This can be any of the following strings: once per day, twice per day, three times per day, four times per day, every morning, or every night.

duration

string

The period for which to take the dose. This can be the number of days (e.g. 120 for 4 months) or it can be any of the following strings: as needed, until symptoms resolve, or ongoing.

additional_info

string

Extra instructions for taking dose (e.g. With meals).

format

string

time_of_day

array

The time(s) of day at which to take the dose. This can be any combination of the following strings: upon waking, morning, afternoon, evening, and bedtime.

resource_ids

array

The Resource IDs to be attached to the Treatment Plan.

labs

array

Lab tests to add to the treatment plan. Replaces existing lab recommendations when provided.

lab_test_id

string

Required

Lab test variant UUID from the labs catalog API.

quantity

string

Reserved for future use. Must be 1 in V1.

instructions

string

Instructions for the patient.

requires_fasting

string

Whether fasting is required.

sample_collection

string

Sample collection option. One of patient_chooses, in_office_phlebotomy, or practitioner_sample_collection.

sample_collection_provider_id

string

UUID of the sample collection provider. When omitted, the lab company's default provider is used.

expected_collection_date

string

Expected sample collection date (ISO 8601).

lab_recommendations

array

Alias for labs. Accepts the same write fields, or the read-only response shape (including nested tests[].id).

variant_id

string

Lab test variant UUID. Alternative to labs[].lab_test_id.

lab_test_id

string

Lab test variant UUID from the labs catalog API.

instructions

string

Instructions for the patient.

requires_fasting

string

Whether fasting is required.

sample_collection

string

Sample collection option. One of patient_chooses, in_office_phlebotomy, or practitioner_sample_collection.

sample_collection_provider_id

string

UUID of the sample collection provider. When omitted, the lab company's default provider is used.

expected_collection_date

string

Expected sample collection date (ISO 8601).

tests

array

Nested tests from a treatment plan response. Uses tests[].id as the lab test variant UUID.

id

string

Lab test variant UUID from a prior response.

lab_test_id

string

Lab test variant UUID from the labs catalog API.

variant_id

string

Lab test variant UUID.

is_labs_practitioner_pay

boolean

Whether the practitioner pays for labs. Required when using sample_collection: practitioner_sample_collection.

metadata

object

Metadata to be attached to the treatment_plan.

id

string

Your system's unique treatment_plan identifier.

PATCH /api/clinic/treatment_plans/{id}

curl -X 'PATCH' "https://api-us-snd.fullscript.io/api/clinic/treatment_plans/{id}" \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
        -d $'{
  "personal_message": "string",
  "recommendations": [
    {
      "variant_id": "string",
      "units_to_purchase": "string",
      "refill": "string",
      "take_with": "string",
      "dosage": {
        "amount": "string",
        "frequency": "string",
        "duration": "string",
        "additional_info": "string",
        "format": "string",
        "time_of_day": "array"
      }
    }
  ],
  "resource_ids": "array",
  "labs": [
    {
      "lab_test_id": "string",
      "quantity": "string",
      "instructions": "string",
      "requires_fasting": "string",
      "sample_collection": "string",
      "sample_collection_provider_id": "string",
      "expected_collection_date": "string"
    }
  ],
  "lab_recommendations": [
    {
      "variant_id": "string",
      "lab_test_id": "string",
      "instructions": "string",
      "requires_fasting": "string",
      "sample_collection": "string",
      "sample_collection_provider_id": "string",
      "expected_collection_date": "string",
      "tests": [
        {
          "id": "string",
          "lab_test_id": "string",
          "variant_id": "string"
        }
      ]
    }
  ],
  "is_labs_practitioner_pay": "boolean",
  "metadata": {
    "id": "string"
  }
}'

Responses

200

OK

403

Forbidden

422

Unprocessable Entity

Create an in-office checkout

The in_office_checkout object takes a treatment_plan. It uses the patient from the treatment_plan to:

a) clear out anything in the patient's cart.

b) populate the patient's cart with the treatment plan.

c) return a url on Fullscript so that a practitioner can fullfill an in-office checkout.

Arguments

treatment_plan_id

string

Required

Unique ID for the Treatment Plan

POST /api/clinic/treatment_plans/{treatment_plan_id}/in_office_checkout

curl -X 'POST' "https://api-us-snd.fullscript.io/api/clinic/treatment_plans/{treatment_plan_id}/in_office_checkout" \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

201

Created

404

Not Found

422