Treatment plan dynamic link

The secret sauce behind your Fullscript Redirect “Recommend with Fullscript” button is the dynamic link that you connect to it. The Fullscript APIs offer two possible links: draft treatment plan and new treatment plan.

For the best user experience, call our create a draft treatment plan endpoint and include patient information in your request. For a more generic experience where the practitioner finds or creates the patient themselves, use retrieve a new treatment plan to get a generic link for the current practitioner.

Either way, in the header of your request, include the practitioner or staff member’s OAuth access_token as the bearer token. This identifies who is using Fullscript, and will ask them to sign in if they have signed out.


Don’t hard code your dynamic link urls, instead use the endpoint to get the redirect_url each time. The value specified in redirect_url can change (and is different between sandbox and production environments!)

Your application can support either of the following treatment plan creation scenarios:

  1. a Fullscript practitioner is drafting a patient treatment plan
  2. a Fullscript staff member is writing the draft plan on behalf of a practitioner

To get the draft treatment plan link, you need:

To determine your user’s Fullscript account type (practitioner or staff member), check the current user’s access_token > resource_owner > type.

userType = token.resource_owner.type;

Find the applicable practitioner_id for your call by examining the relevant user’s access_token > resource_owner > id.

if (userType == “practitioner”) {
   practitionerId =;

You can optionally provide information about the patient the practitioner is working with. If you choose to do so, the patient’s email address is required.

curl -X "POST" "" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \
  -d $'{
  "patient": {
    "email": ""
  "treatment_plan": {
    "practitioner_id": "x1x0196x-5615-4874-xxx4-48x459180x09"

If your query includes patient info, but Fullscript can’t find a matching patient in your clinic, a new patient record is automatically created for you, and a welcome email will be sent to the patient.


Be careful about the email addresses you use during development and testing! Those addresses will receive a welcome email.

You can’t include the patient’s first or last name without an email address, or you’ll get an error due to incomplete data:

Bearer Sax65b94DFHn1va6Y3F-VveBgABX-t8C-3qWyuS1eNI
   error: `["Last name can't be blank", "Email can't be blank", "Email is invalid"]`

Whether the call creates a new Fullscript patient or matches with an existing one, the response includes the dynamic link where you’ll forward the practitioner.

Find the redirect_url nested under dynamic_links in the draft treatment plan response.

redirectURL = response.dynamic_links.redirect_url;


There’s no time limit on this draft treatment plan link, so you can request it when the page loads or wait and only request it when the user clicks your “Recommend with Fullscript” button. Get a fresh new link after using this one though, because the link is tied to the treatment plan’s id and future use of the same link opens the same treatment plan, not to a new one.

If a patient record was created or found, the practitioner lands on the Fullscript patient record, ready to add a treatment plan. Should the practitioner feel the match is incorrect, they can use the dropdown toggle next to the patient name to switch the patient they are reviewing.

Screen capture of the Fullscript Web App, open to the patient's treatment plan page

If no patient data was forwarded, the practitioner lands on a generic page (same as the new treatment plan link, below) where they’re able to search or create a patient record on Fullscript.


Remember to set the dynamic link to open in a new tab so the practitioner can easily return to your app after saving the treatment plan.

The new treatment plan link is a GET method, so there’s no patient data or other body information to provide.

curl -X GET  \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \

The response includes the dynamic link where you’ll forward the practitioner.

Find the redirect_url directly at the top of the new treatment plan response.

redirectURL = response.redirect_url;

When the practitioner opens this link, they’re presented with the option to create or find a patient.

Screen capture of the Fullscript Web App, open to the select/find a patient option on the new treatment plan page


Remember to set the dynamic link to open in a new tab so the practitioner can easily return to your app after saving the treatment plan.

Display the new treatment plan

Congratulations! With the steps above complete, you have your basic Fullscript Redirect integration working. Now, let’s work on a simple augmentation to improve the practitioner experience by copying the treatment plan details to the practitioner’s patient screen in your app.

To do this, we recommend subscribing to our webhooks which will automatically alert you of the new treatment plan. If webhooks won’t work for your infrastructure, you can also use our REST API treatment plans endpoint.


Webhooks are a type of API where we push data to your app instead of you pulling it from Fullscript.

When your app is subscribed to the Treatment plan created webhook, you’ll receive automatic notification of all new treatment plans. When you receive this notification, you can update the page the practitioner is viewing.

We have a handy webhook tutorial that provides everything you’ll need to know about working with webhooks.

Treatment plan endpoint

If you can’t or prefer not to implement webhook support, you can still show the practitioner their most recently created treatment plan using our REST APIs.

To do this, give the practitioner a button that requests a refresh of the patient data. While refreshing the data, call our treatment_plans API to find the latest treatment plan(s) for the patient.

Get the list of available treatment plans for a patient, and their respective created_at date, with treatment_plans.

Then retrieve the details of an individual plan with retrieve-a-treament-plan.


The call to request treatment plans requires the patient id. If your app uses the draft treatment plan link mechanism, the return for this call includes the patient id. Otherwise, obtain the patient id with a patient search.