Pagination

All top-level list endpoints can be paginated. They return a meta tag that contains all pagination data.

Example Request

curl "https://api-us-snd.fullscript.io/api/clinic/patients?page[number]=2&page[size]=20" \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

{
  "patients": [
    {...}
  ],
  "meta": {
    "current_page": 2,
    "next_page": null,
    "prev_page": 1,
    "total_pages": 2,
    "total_count": 40
  }
}

The maximum page size is 100.

Request IDs

All API requests sent will respond with an X-Request-Id in its response header. This value uniquely identifies each request. If you are having trouble with a particular request please provide the X-Request-Id identifier for the fastest possible resolution.

Example

'x-request-id: 06ded6a2-cb35-43e7-9f83-a4b705e3e588'

Versioning

The API version you use controls the behaviour of the API. The first time you register to use Fullscript's API you will be assigned the latest version.

The current version for Fullscript's API is Version 2. If we ever make a breaking change to the API we will release a new dated patch_version with the new behaviour. We do this to avoid breaking any of your code. It's up to you to upgrade if / when you want to.

The latest patch_version is 2020-02-14.

Backwards compatible changes

The Fullscript API considers the following changes to be backwards compatible (ie. non-breaking changes).

  • Adding new API resources
  • Adding new optional request parameters to an existing resource
  • Adding new keys/attributes to existing API responses
  • Changing the order of parameters in an existing API response
  • Changing the format or length of IDs or strings

Rate Limits

The Fullscript API has safeguards to limit the number of requests that can be made in a given timeframe. This helps maximize the API's stability and reliability when dealing with bursts of incoming traffic.

The current rate limit (across all API endpoints) is 5000 requests in a rolling 5m period.

Applications that send many requests in quick succession may see error responses.

Clinic

This endpoints retrieves information about the clinic provided from the X-FS-Clinic-Key.

Retrieve a clinic

This endpoints retrieves information about the clinic provided from the X-FS-Clinic-Key.

Arguments

No arguments...

GET

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

Responses

200

OK

403

Forbidden

Staff

The staff object contains a record of all available staff members that belong to a clinic. The API allows you to create and update staff members. It also allows you to list all staff and find individual staff members.

List all staff

This resource allows you to list all of a clinic's staff.

Arguments

No arguments...

GET

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

Responses

200

OK

403

Forbidden

Create a staff member

Creates a new staff member

Arguments

email

string

REQUIRED

Unique Email for the staff member

first_name

string

REQUIRED

Staff member's first name

last_name

string

REQUIRED

Staff member's last name

metadata

object

Metadata to be attached to the staff member.

id

string

Your system's unique staff identifier.

POST

curl -X 'POST' "https://api-us-snd.fullscript.io/api/clinic/staff" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
  -d $'{
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "metadata": {
    "id": "string"
  }
}'

Responses

201

Created

403

Forbidden

422

Unprocessable Entity

Retrieve a staff member

Retrieves an existing staff member. You need to supply the unique ID for the staff member.

Arguments

id

string

REQUIRED

Unique ID for the staff member

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Update a staff member

Updates a specific staff member with the attributes that you pass in. Parameters not provided will remain unchanged.

Arguments

id

string

REQUIRED

Unique Identifier for the staff member

email

string

Unique Email for the staff member

first_name

string

Staff member's first name

last_name

string

Staff member's last name

metadata

object

Metadata to be attached to the staff member.

id

string

Your system's unique staff identifier.

PATCH

curl -X 'PATCH' "https://api-us-snd.fullscript.io/api/clinic/staff/{id}" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
  -d $'{
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "metadata": {
    "id": "string"
  }
}'

Responses

200

OK

403

Forbidden

404

Not Found

422

Unprocessable Entity

Practitioners

The practitioner object contains a record of all available practitioners that belong to a clinic. The API allows you to create and update practitioners. It also allows you to list all practitioners and find individual practitioners.

List all practitioners

This resource allows you to list all of a clinic's practitioners.

Arguments

No arguments...

GET

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

Responses

200

OK

403

Forbidden

Create a practitioner

Creates a new practitioner

Arguments

practitioner_type_id

string

REQUIRED

Unique Identifier for the Practitioner's Type

email

string

REQUIRED

Unique Email for the Practitioner

first_name

string

REQUIRED

Practitioner's first name

last_name

string

REQUIRED

Practitioner's last name

metadata

object

Metadata to be attached to the practitioner.

id

string

Your system's unique practitioner identifier.

POST

curl -X 'POST' "https://api-us-snd.fullscript.io/api/clinic/practitioners" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
  -d $'{
  "practitioner_type_id": "string",
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "metadata": {
    "id": "string"
  }
}'

Responses

201

Created

403

Forbidden

404

Not Found

Retrieve a practitioner

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

Arguments

id

string

REQUIRED

Unique ID for the Practitioner

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Update a practitioner

Updates a specific practitioner with the attributes that you pass in. Parameters not provided will remain unchanged.

Arguments

id

string

REQUIRED

Unique Identifier for the Practitioner

email

string

Unique Email for the Practitioner

first_name

string

Practitioner's first name

last_name

string

Practitioner's last name

metadata

object

Metadata to be attached to the practitioner.

id

string

Your system's unique practitioner identifier.

PATCH

curl -X 'PATCH' "https://api-us-snd.fullscript.io/api/clinic/practitioners/{id}" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
  -d $'{
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "metadata": {
    "id": "string"
  }
}'

Responses

200

OK

403

Forbidden

404

Not Found

Practitioner Types

The practitioner type object contains details for all the practitioner types available. The API allows you to list all practitioner types.

List all practitioner types

This resource allows you to list all practitioner types.

Arguments

No arguments...

GET

curl "https://api-us-snd.fullscript.io/api/catalog/practitioner_types" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

Protocols

The protocol object contains a record of all treatment plan protocols made by, shared with a practitioner or created by Fullscript. Protocols use a treatment plan as a template that can be re-used when writing prescriptions. Protocols were previously known as templates.

List all Fullscript protocols

The Fullscript protocol object contains a list of all treatment plan protocols that have been created by Fullscript.

Arguments

sort_by

string

Accepts a name argument.

order_by

string

Can take an argument of ASC or DESC.

GET

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

Responses

200

OK

List all practitioner protocols

The practitioner protocol object contains a record of all treatment plan protocols that belong to a practitioner.

Arguments

practitioner_id

string

REQUIRED

Unique ID for the Practitioner

current_state

string

Takes an argument of active, draft or cancelled to return active, draft or cancelled protocols.

sort_by

string

Accepts one of the following arguments: name or current_state.

order_by

string

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

ownership_type

string

Takes an argument of owned, shared or all to return only protocols created by the practitioner, only protocols shared with the practitioner, or both protocols created by and shared with the practitioner, respectively. If this argument is not included, only protocols created by the practitioner are returned.

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

422

Unprocessable Entity

Retrieve a protocol

Retrieves an existing protocol.

Arguments

id

string

REQUIRED

Unique identifier of the protocol.

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Templates

The template object contains a record of all treatment plan templates made by a practitioner. Templates use a treatment plan as a template that can be re-used when writing prescriptions. Templates are soon being deprecated and replaced with protocols.

List all practitioner templates

The practitioner template object contains a record of all treatment plan templates that belong to a practitioner.

Arguments

practitioner_id

string

REQUIRED

Unique ID for the Practitioner

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Retrieve a template

Retrieves an existing template.

Arguments

id

string

REQUIRED

Unique identifier of the Template.

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Labs

The Lab object contains a record of all ordered labs for a patient. Labs begin as recommendations within a treatment plan. Once purchased by the patient, they become lab orders. Lab orders can contain one or more tests and return one or more results.

New to Labs? Start with the Labs integration guide for an overview of lab status transitions, webhook behavior, and result mapping best practices.

List all lab orders

Lists all ordered labs.

Arguments

patient_id

string

Filter orders by patient_id.

GET

curl "https://api-us-snd.fullscript.io/api/clinic/labs/orders" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

404

Not Found

Retrieve a lab order

Retrieves a ordered lab.

Arguments

id

string

REQUIRED

Unique identifier of the lab order.

GET

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

Responses

200

OK

404

Not Found

Retrieve a lab test

Retrieves a lab test.

Note: Lab tests are returned separately from lab results. There is currently no guaranteed one-to-one mapping between results[] and tests[] in the lab order object. See the Labs Integration Guide for recommendations.

Arguments

id

string

REQUIRED

Unique identifier of the lab test.

GET

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

Responses

200

OK

404

Not Found

Resources

The resource object contains a record of all resources made by or shared with a practitioner. The API allows you to create, update, and remove resources. It also allows you to retrieve resources linked to a treatment plan.

List all practitioner resources

Lists all Resources that the Practitioner has access to.

Arguments

practitioner_id

string

REQUIRED

Unique ID for the Practitioner

GET

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

Responses

200

OK

Create a resource

Creates a new Resource for the Practitioner. Only the following file types are allowed: jpg, jpeg, png, pdf, doc, xlsx, pptx.

Arguments

practitioner_id

string

REQUIRED

The unique ID of the practitioner.

type

string

The type of resource. Can be any of the following strings: Guide, Handout, Infographic, Meal plan, or Workbook.

category

string

The category of the resource. Can be any of the following strings: Nutrition, Lifestyle, Physical activity, Supplements, or Health conditions.

attachment

string

REQUIRED

The resource that is being uploaded.

name

string

REQUIRED

The name of the resource that is being uploaded.

treatment_plan_id

string

The treatment plan ID with which the resource is being associated.

save_to_library

string

REQUIRED

A boolean value that signifies whether the resource should be saved to the practitioner's resource library.

POST

curl -X 'POST' "https://api-us-snd.fullscript.io/api/clinic/practitioners/{practitioner_id}/resources" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
  -d $'{
  "type": "string",
  "category": "string",
  "attachment": "string",
  "name": "string",
  "treatment_plan_id": "string",
  "save_to_library": "string"
}'

Responses

200

OK

404

Not Found

422

Unprocessable Entity

Retrieve a practitioner's resource

Retrieves a Resource that the Practitioner has access to.

Arguments

practitioner_id

string

REQUIRED

Unique ID for the Practitioner.

id

string

REQUIRED

Unique ID for the Resource.

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Update a resource

Updates a Practitioner's Resource.

Arguments

practitioner_id

string

REQUIRED

Unique ID for the Practitioner.

id

string

REQUIRED

Unique ID for the Resource.

PUT

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

Responses

200

OK

403

Forbidden

422

Unprocessable Entity

Delete a resource

Deletes an existing Practitioner's Resource.

Arguments

practitioner_id

string

REQUIRED

Unique ID for the Practitioner.

id

string

REQUIRED

Unique ID for the Resource.

DELETE

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

Responses

204

No Content

403

Forbidden

404

Not Found

List All Fullscript Resources

The Fullscript resource object contains a list of all resources that have been created by Fullscript.

Arguments

No arguments...

GET

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

Responses

200

OK

403

Forbidden

Metadata

Metadata allows you to update specific objects in Fullscript with an ID of your choosing. Currently we support updating Patient, Practitioner, Staff, and TreatmentPlan objects with metadata.

Metadata is useful for storing identifiers from your system into Fullscript — making it easier to link up users from your system into ours. For example, you could use metadata to attach your system's user ID to a Practitioner or Patient. Then using the metadata endpoint you can retrieve that same object using the ID's from your system.

Find objects

To look up objects by your system's identifier. The object type and ID can be provided to filter results.

Arguments

id

string

Your system's identifier.

type

object

The type of object. Can be one of patient, practitioner, staff, or treatment_plan.

GET

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

Responses

200

OK

403

Forbidden

Patients

The patient object contains a record of all available patients that belong to a clinic. The API allows you to create and update patients. It also allows you to list all patients and find individual patients.

List all dependents

This resource allows you to retrieve all dependents linked to a guardian patient.

Arguments

patient_id

string

REQUIRED

The ID of the guardian patient to list dependents for.

GET

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

Responses

200

OK

404

Not Found

List all patients

This resource allows you to list all of a clinic's patients.

Arguments

patient_type

string

The type of patient to filter by. Valid options are all, dependent, or guardian. If not provided, all patients will be returned.

GET

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

Responses

200

OK

403

Forbidden

Create a patient

Creates a new patient

Arguments

email

string

REQUIRED

Unique Email for the Patient

first_name

string

REQUIRED

Patient's first name

last_name

string

REQUIRED

Patient's last name

date_of_birth

string

Patient's date of birth in the format yyyy-mm-dd

gender

string

Biological sex of the patient. Valid options are 'male', 'female', or 'x'.

mobile_number

string

Patient's mobile number in the format +12223334444

send_welcome_email

string

Sends a welcome email to the patient upon successful creation. Defaults to true.

discount

string

Patient discount level (in percentage). This discount does not include the clinic discount. Defaults to 0.

metadata

object

Metadata to be attached to the patient.

id

string

Your system's unique patient identifier.

POST

curl -X 'POST' "https://api-us-snd.fullscript.io/api/clinic/patients" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
  -d $'{
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "date_of_birth": "string",
  "gender": "string",
  "mobile_number": "string",
  "send_welcome_email": "string",
  "discount": "string",
  "metadata": {
    "id": "string"
  }
}'

Responses

201

Created

403

Forbidden

422

Unprocessable Entity

Retrieve a patient

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

Arguments

id

string

REQUIRED

Unique ID for the Patient

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Update a patient

Updates a specific patient with the attributes that you pass in. Parameters not provided will remain unchanged.

Arguments

id

string

REQUIRED

Unique ID for the Patient

email

string

Unique Email for the Patient

first_name

string

Patient's first name

last_name

string

Patient's last name

date_of_birth

string

Patient's date of birth in the format yyyy-mm-dd

gender

string

Biological sex of the patient. Valid options are 'male', 'female', or 'x'.

mobile_number

string

Patient's mobile number in the format +12223334444

discount

string

Patient discount level (in percentage). This discount does not include the clinic discount. Defaults to 0.

metadata

object

Metadata to be attached to the patient.

id

string

Your system's unique patient identifier.

PATCH

curl -X 'PATCH' "https://api-us-snd.fullscript.io/api/clinic/patients/{id}" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
  -d $'{
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "date_of_birth": "string",
  "gender": "string",
  "mobile_number": "string",
  "discount": "string",
  "metadata": {
    "id": "string"
  }
}'

Responses

200

OK

403

Forbidden

404

Not Found

422

Unprocessable Entity

Search for patients

This resource allows you to search for patients by first_name, last_name, or by email.

Arguments

query

string

Search for patients matching a query string.

patient_type

string

Filter by patient type. Valid options are all, dependent, or guardian. If not provided, patients with no dependents will be returned.

GET

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

Responses

200

OK

403

Forbidden

Address

The address object contains a record of all addresses that a patient has made. In this API you can look up the address on an individual patient.

List All Patient Addresses

The address object contains a record of all addresses that belong to a patient.

Arguments

patient_id

string

REQUIRED

Unique ID for the patient.

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Orders

The order object contains a record of all completed or refunded orders that a patient has made.

List all orders

This resource returns all orders for the clinic and can be filtered by the following attributes.

Arguments

patient_id

string

Filter orders by patient_id.

treatment_plan_id

string

Filter orders by treatment_plan_id.

completed_at

string

Filter orders by completed_at. The date must be formatted as follows yyyy-mm-dd.

  • less than: Return orders where the completed_at date is less than. <yyyy-mm-dd.
  • greater than: Return orders where the completed_at date is greater than. >yyyy-mm-dd.
  • within a range: Return orders where the completed_at date is with in a range. yyyy-mm-dd..yyyy-mm-dd.
type

string

Filter orders by type. The default value is all, which includes all types of orders. To filter specifically for lab orders, use the value labs.

order_number

string

Filter orders by order_number.

sort_by

string

Accepts one of the following arguments: patient_id, treatment_plan_id, completed_at and order_number.

order_by

string

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

GET

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

Responses

200

OK

403

Forbidden

Retrieve an Order

Retrieves an existing Order.

Arguments

id

string

REQUIRED

Unique identifier of the Order.

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

List all patient orders

The patient order object contains a record of all completed or refunded orders that belong to a patient.

Arguments

patient_id

string

REQUIRED

Unique ID for the Patient

GET

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

Responses

200

OK

403

Forbidden

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

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

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

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

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.

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

REQUIRED

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

string

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.

POST

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

Responses

201

Created

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

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.

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

string

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

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": "string"
      }
    }
  ],
  "resource_ids": "array",
  "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

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

Unprocessable Entity

Dynamic link

Returns a redirect_url that enables access to a draft treatment plan. This endpoint optionally finds or creates a patient record to associate with the treatment plan. It supports dependent accounts and includes a user interface that allows practitioners to manually match patients and practitioners if automatic matching is unsuccessful. When a match is automatically found, the patient is preselected for the practitioner.

OAuth scopes required:

  • clinic:write - required for all requests to this endpoint.
  • patients:write - required if the request may result in patient creation.

Arguments

treatment_plan

object

Treatment plan information for dynamic link.

practitioner_id

string

Practitioner's id used to create the draft treatment_plan.

patient

object

Patient information used for creating a match with a Fullscript patient, or pre-filling information to create a new patient in Fullscript

id

string

Fullscript patient id.

external_id

string

Unique patient id to create a match with a fullscript patient

email

string

Unique Email for the Patient.

first_name

string

Patient's first name.

last_name

string

Patient's last name.

date_of_birth

string

Patient's date of birth in the format yyyy-mm-dd.

gender

string

Biological sex of the patient. Valid options are 'male', 'female', or 'x'.

mobile_number

string

Patient's mobile number in the format +12223334444.

discount

string

Patient discount level (in percentage). This discount does not include the clinic discount. Defaults to 0.

send_welcome_email

string

Sends a welcome email upon successful patient creation and treatment plan creation. Defaults to true.

entrypoint

string

Specifies which page the redirect_url will open. Defaults to "catalog" if not specified.

  • catalog: Starts the user on the product catalog page (default).
  • labs: Starts the user on the labs page.

POST

curl -X 'POST' "https://api-us-snd.fullscript.io/api/clinic/dynamic_links/gateway/treatment_plans" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
  -d $'{
  "treatment_plan": {
    "practitioner_id": "string"
  },
  "patient": {
    "id": "string",
    "external_id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "date_of_birth": "string",
    "gender": "string",
    "mobile_number": "string",
    "discount": "string",
    "send_welcome_email": "string"
  },
  "entrypoint": "string"
}'

Responses

200

OK

400

Bad Request

Returns a redirect_url for a new treatment plan.

Arguments

No arguments...

GET

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

Responses

200

OK

403

Forbidden

fyi

This endpoint does not support dependent accounts. If you are working with dependent accounts, use the Create a Draft Treatment Plan Link with Patient Matching UI endpoint instead.

Returns a redirect_url that enables access to a draft treatment plan. This endpoint optionally finds or creates a patient record to associate with the treatment plan.

OAuth scopes required:

  • clinic:write - required for all requests to this endpoint.
  • patients:write - required if the request may result in patient creation.

Arguments

treatment_plan

object

REQUIRED

Treatment plan information for dynamic link.

practitioner_id

string

REQUIRED

Practitioner's id used to create the draft treatment_plan.

patient

object

Find or create a Patient.

email

string

Unique Email for the Patient.

first_name

string

Patient's first name.

last_name

string

Patient's last name.

date_of_birth

string

Patient's date of birth in the format yyyy-mm-dd.

gender

string

Biological sex of the patient. Valid options are 'male', 'female', or 'x'.

mobile_number

string

Patient's mobile number in the format +12223334444.

discount

string

Patient discount level (in percentage). This discount does not include the clinic discount. Defaults to 0.

send_welcome_email

string

Sends a welcome email upon successful patient creation and treatment plan creation. Defaults to true.

entrypoint

string

Specifies which page the redirect_url will open. Defaults to "catalog" if not specified.

  • catalog: (default) Starts the user on the product catalog page.
  • labs: Starts the user on the labs page.

POST

curl -X 'POST' "https://api-us-snd.fullscript.io/api/clinic/dynamic_links/treatment_plans" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \ 
  -d $'{
  "treatment_plan": {
    "practitioner_id": "string"
  },
  "patient": {
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "date_of_birth": "string",
    "gender": "string",
    "mobile_number": "string",
    "discount": "string",
    "send_welcome_email": "string"
  },
  "entrypoint": "string"
}'

Responses

200

OK

400

Bad Request

422

Unprocessable Entity

Returns a redirect_url for editing an existing treatment plan. The treatment plan provided must have a state of draft or active.

Arguments

id

string

REQUIRED

Unique ID for the Treatment Plan

entrypoint

string

Target treatment plan page to open with the redirect_url. Defaults to "catalog"

  • catalog: (default) Starts the user on the product catalog page.
  • labs: Starts the user on the labs page.

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Products

The product object contains details for all products on the Fullscript platform. The API allows you to list all products and find individual products.

List all products

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.

This resource allows you to list all products.

Arguments

No arguments...

GET

curl "https://api-us-snd.fullscript.io/api/catalog/products" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

Retrieve a product

Retrieves an existing product. If the practitioner has set custom dosage instructions for the product, the custom_dosage object is included in the response. Specify the pracitioner with practitioner_id (defaults to current practitioner, when applicable).

Arguments

id

string

REQUIRED

Unique identifier for the Product

practitioner_id

string

Unique Practitioner ID. Include to retrieve a specific practitioner's custom dosage instructions for the product. Defaults to the practitioner who owns current access token, if applicable (access token's resource owner type is Practitioner). Custom dosage is returned in the custom_dosage object.

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

List similar products

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.

This endpoint allows you to list similar products that have been curated by Fullscript's licensed health professionals. It is in order from most to least popular.

Arguments

product_id

string

REQUIRED

Unique identifier for the Product

GET

curl "https://api-us-snd.fullscript.io/api/catalog/products/{product_id}/similar" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

404

Not Found

Categories

The category object contains a record of all categories from a clinic.

List all category products

This resource allows you to list all of a category's products. The list is sorted in ascending order by the product's name, by default.

Arguments

category_id

string

REQUIRED

Unique ID for the Category.

sort_by

string

Accepts a name argument.

order_by

string

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

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Retrieve a Category

Retrieves an existing Category.

Arguments

id

string

REQUIRED

Unique identifier of the Category.

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

List all categories

This resource allows you to list all of a clinic's categories.

Arguments

No arguments...

GET

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

Responses

200

OK

403

Forbidden

Product search

Search for products

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.

This resource allows you to search for products using Fullscript's opensearch implementation. This endpoint takes into consideration brand segmentation (not all clinics have access to all brands) and will only show products and brands that your clinic has available to them.

Note: Filter arguments that accept an array can be specified in the query string like this:
?allergen_ids[]=id_1&allergen_ids[]=id_2

Arguments

query

string

Search for products matching a query string.

allergen_ids

string

Provide an array of allergen ids to filter results.

brand_id

string

Search for products by brand_id.

ingredient_ids

string

Provide an array of ingredient ids to filter results.

supplement_type_ids

string

Provide an array of supplement type ids to filter results.

third_party_certification_ids

string

Provide an array of third party certification ids to filter results.

GET

curl "https://api-us-snd.fullscript.io/api/catalog/search/products" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

404

Not Found

Allergens

Attributes about a product as they relate specifically to ingredients known to cause allergic reactions / ingredients known to want to be avoided (e.g. 'Peanut free'). They are not attested by third parties.

The allergen object contains details for all allergens listed on the Fullscript platform. The API allows you to list all allergens and find individual allergens.

List all allergens

This resource allows you to list all allergens.

Arguments

No arguments...

GET

curl "https://api-us-snd.fullscript.io/api/catalog/allergens" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

Retrieve an allergen

Retrieves details for an existing allergen.

Arguments

id

string

REQUIRED

Unique ID for the allergen

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Brands

The brand object contains details for all brands on the Fullscript platform. The API allows you to list all brands and find individual brands.

List all brands

This resource allows you to list all brands.

Arguments

available

string

Takes an argument of true to return brands that have available products.

clinic_permitted

string

Takes an argument of true to return brands the current clinic has access to.

GET

curl "https://api-us-snd.fullscript.io/api/catalog/brands" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

Retrieve a brand

Retrieves details for an existing brand.

Arguments

id

string

REQUIRED

Unique ID for the Brand

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Ingredients

Supplement ingredients that make up the product (e.g. 'Curcumin').

The ingredient object contains details for all ingredients listed on the Fullscript platform. The API allows you to list all ingredients and find individual ingredients.

List all Ingredients

This resource allows you to list all ingredients.

Arguments

No arguments...

GET

curl "https://api-us-snd.fullscript.io/api/catalog/ingredients" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

Retrieve an ingredient

Retrieves details for an existing ingredient.

Arguments

id

string

REQUIRED

Unique ID for the ingredient

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Supplement Types

Groups of products based on similar attributes (e.g. 'Multivitamins').

The supplement type object contains details for all supplement types listed on the Fullscript platform. The API allows you to list all supplement types and find individual supplement types.

List all supplement types

This resource allows you to list all supplement types.

Arguments

No arguments...

GET

curl "https://api-us-snd.fullscript.io/api/catalog/supplement_types" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

Retrieve a supplement type

Retrieves details for an existing supplement type.

Arguments

id

string

REQUIRED

Unique ID for the supplement type

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Third Party Certifications

Third party certifications are product level filters that are assessed by a party external to the manufacturer (e.g. 'Certified Halal').

The third party certification object contains details for all third party certifications listed on the Fullscript platform. The API allows you to list all third party certifications and find individual third party certifications.

List all third party certifications

This resource allows you to list all third party certifications.

Arguments

No arguments...

GET

curl "https://api-us-snd.fullscript.io/api/catalog/third_party_certifications" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

Retrieve a third party certification

Retrieves details for an existing third party certification.

Arguments

id

string

REQUIRED

Unique ID for the third party certification

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Variants

The variant object contains details about product variants. The API allows you to find individual variants.

Retrieve a variant

Retrieves an existing variant.

Arguments

id

string

REQUIRED

Unique identifier for the Variant.

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

Webhooks

Webhooks allow your application to stay informed with what’s happening on Fullscript. You can subscribe to events and be notified when they happen. Let’s say one of your clinics updates a patient or creates a treatment plan; webhooks allow you to know about those events and take action if needed.

Using webhooks

You can register a single webhook URL through the API Dashboard and subscribe to multiple event types.

When the event occurs—say a treatment plan is created, a patient is updated, or a clinic key is revoked, etc.—Fullscript creates an Event. This Event contains all the relevant information about what just happened. It includes the event's type (ex: treatment_plan.created) and any relevant data to that event.

Once the event is created, Fullscript will send out a payload with the event data via an HTTP POST request to the webhook url that you defined in your account. Note that we only send events to a single endpoint per environment.

Setting up webhooks

Webhooks are configured through the API Dashboard. For each environment that you have setup, you can enter a URL to receive events. This should be a dedicated URL on your server that is setup to receive webhook notifications.

All urls need to use HTTPS. We will validate that your connection is secure and HIPAA compliant before sending any webhook data. For this to work, your server needs to be setup to support HTTPS with a valid certificate.

Responding to a webhook

To acknowledge that you received a webhook notification, your endpoint needs to respond with either a 200 or 201 HTTP status code. Any response codes outside of this range will tell us that the webhook has not been received and will be treated as a failure.

Your endpoint's body must also respond with your challenge token (available in the API Dashboard). This is a security measure to ensure that you own the url in question and it hasn't been hijacked. A successful response could look something like this:

HTTP 200 OK
Content-type: application/json
{ "challenge": "your-secret-challenge-token" }

We will attempt to deliver your webhooks up to 6 times with exponential back off. Webhooks cannot manually be retried, however you can make a query to the events endpoint to reconcile data in case of any missed events.

We will attempt to send event deliveries in order, however that is not a guarantee. We will also attempt to deliver webhooks within 30 minutes from when the event was created. In most cases however, this should be close to instantaneous.

The webhook deliveries endpoint has all the information you need to check how many times we’ve attempted to deliver an event, what the response received was, the status code, and other relevant information.

Time-outs

We set aggressive time-outs for webhook deliveries. If you have to do a bunch of complex logic with the event data, or need to make network requests, it’s possible that the delivery attempt will time-out before we receive a 2xx HTTP status code. To mitigate this, you may want to respond immediately with a 2xx HTTP status code, and then perform your complex logic afterwards.

Handling multiple clinics and integrations

Each event payload comes with both a clinic_id and an integration_id (if relevant). The clinic key is the unique identifier for the clinic. Any clinic events (patient, practitioner, treatment plan, etc.) will be scoped to that clinic through the clinic_id.

Because it's possible for clinics to have multiple integrations enabled, the exact same events will be sent for each integration that a clinic has enabled with you. To mitigate unwanted duplication of events, the integration has to be activated before any webhook events will be sent. This means that it’s been used as least once with a valid X-FS-Clinic-Key and the key has not been revoked. The integration_id allows you to scope events to the relevant integration that is enabled.

Both the clinic_id and integration_id can be retrieved through the API at the clinic endpoint.

Multiple failures

In some circumstances we will disable your endpoint and stop trying to deliver events to it. This can happen when: we receive a 410 HTTP status code or if the delivery attempts are consistently failing for more than 24 hours. In that case your webhook endpoint may be disabled and we will no longer send events to that url.

Re-enabling a disabled webhook can be done through the API Dashboard once you have resolved the issues.

You can see the status (both failed and successful delivery attempts) through the webhook deliveries endpoint.

Webhook versioning

Webhook events follow the same logic as our versioning scheme in the API and it respects the patch_version that you’re on.

Webhooks Security

Checking the Fullscript-Signature header

Fullscript sends a header in the webhook request that can be used in conjunction with your Webhook Secret Key to verify the payload. Here is an example of the header:

Fullscript-Signature: t=1591826856,v1=0c262932b0ac6b4952e2fe24fdf419313984a66f6f442e0b8ec4cb87f2a107ad

This represents the format: t=<timestamp>,v1=<signature>

The signature is generated using a hash-based message authentication code (HMAC) with SHA-256. This hash is generated using 3 things:

  • A UTC timestamp
  • The request_body (The POST message's JSON payload string)
  • Your Webhook Secret Key

The timestamp and request_body are combined to create the payload provided to the hash function. The Webhook Secret Key is used as the key. The same hash can be computed and compared to the signature to verify the request.

To recompute and compare the hash, follow these steps:

  • Extract the timestamp and signature from the header.
  • Create the payload by combining the timestamp and request_body with a single .

Example: payload = '1591826856.{"event":{...<more_json>}}'

  • Compute an HMAC with the SHA256 hash function. Use the Webhook Secret Key as the key. Use the payload string as the message.
  • Compare the result with the signature.
  • If they match, the request payload is legitimate.

Note: The timestamp is generated directly before we send the payload. It is included in the hash payload in order to help prevent replay attacks. We recommend using this to verify the age of a request with a reasonable tolerance. 5 minutes is usually a good default.

List All Webhook Deliveries

This endpoint lists all webhook_deliveries from the last 30 days.

Arguments

attempted_at

string

Filter by attempted_at date. The date must be formatted as follows yyyy-mm-dd.

  • less than: Return webhook deliveries where the attempted_at date is less than. <yyyy-mm-dd.
  • greater than: Return webhook deliveries where the attempted_at date is greater than. >yyyy-mm-dd.
  • within a range: Return webhook deliveries where the attempted_at date is within a range. yyyy-mm-dd..yyyy-mm-dd.
event_id

string

Filter webhook deliveries by event_id.

successfully_delivered

string

Filter webhook deliveries by whether they have been successfully delivered or not. Accepts a string of true or false

sort_by

string

Accepts one of the following arguments: event_id attempted_at.

order_by

string

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

GET

curl "https://api-us-snd.fullscript.io/api/webhooks/deliveries" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

Events

Events allow your integration to stay informed with what’s happening on Fullscript. Let’s say one of your clinics updates a patient, or creates a treatment plan. In each case an Event will be created which allows you to take action if need be.

This Event has all of the relevant information about what just happened. It includes the event's type (say treatment_plan.created) and any relevant data to that event.

Note that we only keep a record of events for the past 30 days.

Also know that events are never created for actions made through the API. We assume that, since you initiated the event, you already know about it! 😀

List All ClinicKey Events

This endpoint lists all clinic_key events from the last 30 days.

  • A clinic_key.revoked event happens when a clinic revokes access to your integration.

  • A clinic_key.activated event happens when the first request is made through the API with a valid X-FS-Clinic-Key—activating the integration.

Arguments

created_at

string

Filter by created_at date. The date must be formatted as follows yyyy-mm-dd.

  • less than: Return events where the created_at date is less than. <yyyy-mm-dd.
  • greater than: Return events where the created_at date is greater than. >yyyy-mm-dd.
  • within a range: Return events where the created_at date is within a range. yyyy-mm-dd..yyyy-mm-dd.
event_type

string

Filter events by event_type.

sort_by

string

Accepts one of the following arguments: event_type created_at.

order_by

string

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

GET

curl "https://api-us-snd.fullscript.io/api/events/clinic_keys" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

Retrieve an Event

This endpoint retrieves details from an Event. Note that event's can only be retrieved if they were made within the last 30 days.

Arguments

id

string

REQUIRED

Unique identifier of the Event

GET

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

Responses

200

OK

403

Forbidden

404

Not Found

List All Lab Order updated Events

This endpoint lists all lab order events from the last 30 days.

  • A lab_order.updated event happens when a lab test result is available or has been ammended.

Arguments

created_at

string

Filter by created_at date. The date must be formatted as follows yyyy-mm-dd.

  • less than: Return events where the created_at date is less than. <yyyy-mm-dd.
  • greater than: Return events where the created_at date is greater than. >yyyy-mm-dd.
  • within a range: Return events where the created_at date is within a range. yyyy-mm-dd..yyyy-mm-dd.
sort_by

string

Accepts a created_at. argument.

order_by

string

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

GET

curl "https://api-us-snd.fullscript.io/api/events/lab_orders" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

List All Order Events

This endpoint lists all order events from the last 30 days.

  • An order.placed event happens when an order has been placed.

Arguments

created_at

string

Filter by created_at date. The date must be formatted as follows yyyy-mm-dd.

  • less than: Return events where the created_at date is less than. <yyyy-mm-dd.
  • greater than: Return events where the created_at date is greater than. >yyyy-mm-dd.
  • within a range: Return events where the created_at date is within a range. yyyy-mm-dd..yyyy-mm-dd.
event_type

string

Filter events by event_type.

sort_by

string

Accepts one of the following arguments: event_type created_at.

order_by

string

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

GET

curl "https://api-us-snd.fullscript.io/api/events/orders" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

List All Patient Events

This endpoint lists all patient events from the last 30 days.

  • A patient.created event happens when a patient is created.

  • A patient.updated event happens when a patient is updated.

  • A patient.emancipated event happens when a patient completes emancipation.

Arguments

created_at

string

Filter by created_at date. The date must be formatted as follows yyyy-mm-dd.

  • less than: Return events where the created_at date is less than. <yyyy-mm-dd.
  • greater than: Return events where the created_at date is greater than. >yyyy-mm-dd.
  • within a range: Return events where the created_at date is within a range. yyyy-mm-dd..yyyy-mm-dd.
event_type

string

Filter events by event_type.

sort_by

string

Accepts one of the following arguments: event_type created_at.

order_by

string

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

GET

curl "https://api-us-snd.fullscript.io/api/events/patients" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

List All Product Events

This endpoint lists all product events from the last 30 days.

  • A product.created event happens when a product is created.

  • A product.updated event happens when a product or one of its variants is updated.

  • A product.description.updated event happens when a product's description is updated.

Arguments

created_at

string

Filter by created_at date. The date must be formatted as follows yyyy-mm-dd.

  • less than: Return events where the created_at date is less than. <yyyy-mm-dd.
  • greater than: Return events where the created_at date is greater than. >yyyy-mm-dd.
  • within a range: Return events where the created_at date is within a range. yyyy-mm-dd..yyyy-mm-dd.
event_type

string

Filter events by event_type.

sort_by

string

Accepts one of the following arguments: event_type created_at.

order_by

string

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

GET

curl "https://api-us-snd.fullscript.io/api/events/products" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Responses

200

OK

403

Forbidden

List All TreatmentPlan Events

This endpoint lists all treatment_plan events from the last 30 days.

  • A treatment_plan.created event happens when a Treatment Plan is created.

  • A treatment_plan.updated event happens when an active Treatment Plan is modified, such as when it is cancelled.

    Note: This webhook does not trigger when a draft becomes active, and patient or practitioner changes are not supported on active plans.

  • A treatment_plan.recommendation.updated event happens when a Treatment Plan's recommendation is updated.

Arguments

created_at

string

Filter by created_at date. The date must be formatted as follows yyyy-mm-dd.

  • less than: Return events where the created_at date is less than. <yyyy-mm-dd.
  • greater than: Return events where the created_at date is greater than. >yyyy-mm-dd.
  • within a range: Return events where the created_at date is within a range. yyyy-mm-dd..yyyy-mm-dd.
event_type

string

Filter events by event_type.

sort_by

string

Accepts one of the following arguments: event_type created_at.

order_by

string

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

GET

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

Responses

200

OK

403

Forbidden