Scheduled maintenance — Monday, June 29, 8:00–9:00 PM ET

Documentation will remain available. Database changes made during this window may not be saved.

API OVERVIEW

Pagination

Request IDs

Versioning

Rate Limits

CLINIC

Clinic

Retrieve a clinic

PATIENTS

Treatment Plans

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

This endpoint is not available for general use. Access is highly restricted, and most requests will not be granted. If you believe your case is critical, you may submit a request for consideration. We will only respond if your request is relevant.

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

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

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

Create a patient treatment plan

This endpoint is restricted

This endpoint is not available for general use. Access is highly restricted, and most requests will not be granted. If you believe your case is critical, you may submit a request for consideration. We will only respond if your request is relevant.

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.

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, 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

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

Update a treatment plan

Updates a Treatment Plan for a patient.

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

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.

resource_ids

array

The Resource IDs to be attached to the Treatment Plan.

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", "metadata": { "id": "string" } }'

Responses

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