NAV

Fullscript API Reference

This is the RESTful API for the Fullscript Dispensary.

There are a couple endpoints available depending on your integration needs. We have separate accounts for the U.S. and Canada. Both have production environments, and we have one sandbox environment than can be used for testing either U.S. or Canada integrations.

Throughout the API documentation we use the sandbox environment for all the examples. The url will be different depending on which region / environment you want.

Root URLs

These are the urls available (dependent on your specific integration needs). Note that all calls to the API need to be made over https. Calls made over http will error.

U.S. API endpoint

  
    "https://api-us.fullscript.io/api/"

Canada API endpoint

  
    "https://api-ca.fullscript.io/api/"

U.S. Sandbox (Testing) API endpoint

  
    "https://api-us-snd.fullscript.io/api/"

Canada Sandbox (Testing) API endpoint

  
    "https://api-ca-snd.fullscript.io/api/"

🇺🇸 U.S. Production

https://api-us.fullscript.io/api/

🇨🇦 Canada Production

https://api-ca.fullscript.io/api/

💡🇺🇸 U.S. Sandbox (Testing)

https://api-us-snd.fullscript.io/api/

💡🇨🇦 Canada Sandbox (Testing)

https://api-ca-snd.fullscript.io/api/

OAuth Authentication

Fullscript uses the OAuth tokens to allow access to its API. We support the standard authorization grant type to obtain an authorization code and then exchange it for a secure token.

Getting started

To get started with OAuth you can create an application in the API Dashboard App. There are a bunch of decisions to make that the API Dashboard App will help walk you through. OAuth requires a url that we can redirect to upon authorization. You'll also need to decide which scopes to setup for your particular application.

Scopes

Scopes allow you to specify exactly what kind of access you require. Scopes limit which data you have access to (and what you can do with it). It is up to the individual practitioner to decide if they want to authorize access to the scopes you have requested. The scopes requested are displayed to the practitioner when asked to authorize and practitioners can always say no. Therefore it is recommended to only setup your application with the scopes that you need—rather than everything.

Note that scopes are linked to the scopes of your application (configured in the API Dashboard app). If you need different scopes for different scenarios then it is recommended to either create multiple applications or setup your scoping such that it can handle most of your use cases.

Also note that once a practitioner has granted access to you, adding new scopes to your application will invalidate any tokens configured with the previous scoping. They would have to re-authenticate and do the OAuth flow again to generate a new token.

Name Description
catalog:read Grants read-only access to the Fullscript catalog. This includes the brand, product, and variant endpoints. This is a default scope, given to all API accounts.
clinic
clinic:read Grants read access to clinic’s account and practitioner information.
clinic:write Grants access to a clinic’s account and can perform actions on behalf of its practitioners. If paired with patients:read treatment plans can be created.
patients
patients:read Grants access to read a patient’s data. This includes any treatment plans made through the API.
patients:write Grants access to create and update a patient’s information.
patients:treatment_plan_history Grants read access to a patient’s historical treatment plan data.
patients:order_history Grants read access to a patient’s order history.

OAuth Flow

The basic OAuth flow can be broken down into 3 steps.

  1. Practitioners are asked to grant access to their Fullscript account
  2. The practitioner is redirected back to your site by Fullscript
  3. Access the API with the token

1. Practitioners are asked to grant access to their Fullscript account

From your site, create a link with our buttons that takes a practitioner to the OAuth authorization page. This url needs its parameters to be formatted to match the settings configured in your OAuth application. The client_id and redirect_uri need to be included and need to match exactly the configuration in your OAuth application—otherwise it will 404. Any scopes you have configured in the OAuth application will automatically be applied.

Example urls:

🇺🇸 U.S. Sandbox (testing)

https://us-snd.fullscript.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_APPLICATIONS_REDIRECT_URI&response_type=code

🇺🇸 U.S. Production

https://api-us.fullscript.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_APPLICATIONS_REDIRECT_URI&response_type=code

🇨🇦 Canada Sandbox (testing)

https://ca-snd.fullscript.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_APPLICATIONS_REDIRECT_URI&response_type=code

🇨🇦 Canada Production

https://api-ca.fullscript.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_APPLICATIONS_REDIRECT_URI&response_type=code

Once here, a practitioner will be asked to login (if not already) or to sign up for a Fullscript account. Then the practitioner will be asked to authorize your OAuth application. They'll be given a detailed list of which scopes are requested and what that means. At this stage they can either authorize or cancel the transaction.

2. The practitioner is redirected back to your site by Fullscript

If the practitioner grants access they'll be redirected back to the redirect_uri that you configured in your OAuth application. A one-time-use access token will be included in the parameters. This access token will expire in 10 minutes.

You'll get something that looks like:

YOUR_APPLICATIONS_REDIRECT_URI?code=476x028x13xxxx52xx4x2xx87x472x735xxx893570x89xx48x9496xxx2418052

Now it's up to you to do the OAuth dance 🕺! The access code can now be used to exchange for an OAuth token. Detailed information about creating an OAuth token can be found here but the basic gist is: you make an API request with your OAuth application credentials and access token. Then if successful, you'll get back a response with an OAuth token.

OAuth tokens expire within 2 hours. But they also come with a refresh token so that you can refresh an expired token when needed.

3. Access the API with the token

Once you've successfully received and stored the OAuth token, it can be used to authenticate with the API. Just include the token in your header when making a request, like so:

{ "Authorization" => "Bearer 96x5x67x09168xx64x4x8xx5xx541xxxxx38x10071xx1xxx24x66x0xxxxxxx74" }

And that's it!

OAuth Token

Attributes

Create an OAuth Token

Creates a new OAuth token or refreshes an expired token.

Example Request

  
curl -X "POST" "https://api-us-snd.fullscript.io/api/oauth/token" \
  -H 'Content-Type: application/json' \
  -d $'{
  "grant_type": "authorization_code",
  "client_id": "83x92x21xx29x643xx9954x8x2xx651xxx87x66521x08x9x2x408x26x801x394",
  "client_secret": "5305x72xxx6xx7xx4848xxxxx040x4xx4xx965xx566x662xxxxx6x7xxx5x730x",
  "code": "x8x9xx06x9138x41x0x4xx3xxx726x0x2749xxx798x1x7x3x46x902x4068664x",
  "redirect_uri": "https://fullscript.io/api"
}'

Example Response

  
{
  "oauth": {
    "access_token": "96x5x67x09168xx64x4x8xx5xx541xxxxx38x10071xx1xxx24x66x0xxxxxxx74",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "xxxx4x98xxxx7x03xxxxxx73x95x2514x0xx2x9xx15882xx7947496376x343x9",
    "scope": "catalog:read",
    "created_at": "2018-10-16T04:00:00.000Z",
    "resource_owner": {
      "id": "xx7x357x-9x36-xxxx-x553-7x3xx398xxx",
      "type": "Clinic"
    }
  }
}

HTTP Request

POST https://api-us-snd.fullscript.io/api/oauth/token

Arguments

Revoke an OAuth Token

Revokes an OAuth token.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/oauth/revoke" \
  -H 'Content-Type: application/json' \
  -d $'{
  "client_id": "83x92x21xx29x643xx9954x8x2xx651xxx87x66521x08x9x2x408x26x801x394",
  "client_secret": "5305x72xxx6xx7xx4848xxxxx040x4xx4xx965xx566x662xxxxx6x7xxx5x730x",
  "token": "xx7xxxxx7xxxx3xxxx5xxx9xx4xxxxxx1xxxx3x9xxx"
}'

Example Response

  
{
}

HTTP Request

https://api-us-snd.fullscript.io/api/oauth/revoke

Arguments

Quick Integration

Fullscript offers a way to implement quick integration, it allows you to integrate with fullscript while spending minimal time on development. Quick integration consists of implementing a button in your EHR which will call a dynamic link endpoint. This endpoint will return a redirect_url on the fullscript platform to let a practitioner take an action. You must open a new tab with the url value of the redirect_url provided by the endpoint.

This will let the practitioner take essential actions without the need to make a custom integration that is embedded in your EHR.

You can couple this with webhook events to be notfied of actions taken with in fullscript and then reflect these changes in your EHR.

Please do not hard code these urls, instead use the endpoint to get the redirect_url. We will be adding the ability to pass in arguments and based on these arguments the value of redirect_url will change.

Dynamic link

This resource will return a redirect_url on the fullscript platform for a treatment_plan.

Attributes

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

Example Request

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

Example Response

  
{
  "dynamic_links": {
    "redirect_url": "https://api-us-snd.fullscript.io/p/treatment_plans/101010/edit",
    "treatment_plan": {
      "id": "x1x01x6x-5615-4874-xxx4-48x459180x09",
      "state": "active",
      "available_at": "2019-10-16"
    },
    "patient": {
      "id": "x1x0196x-5615-4874-xxe4-48x459180x09",
      "first_name": "Example",
      "last_name": "Patient",
      "email": "patient@example.com",
      "date_of_birth": null,
      "gender": null,
      "discount": 0,
      "total_discount": 0,
      "mobile_number": "",
      "text_message_notification": 0
    }
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/dynamic_links/treatment_plans/:id

Arguments

Returns a redirect_url for a new treatment plan.

Example Request

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

Example Response

  
{
  "redirect_url": "https://api-us-snd.fullscript.io/p/treatment_plans/new?client_id=83x92x21xx29x643xx9954x8x2xx651xxx87x66521x08x9x2x408x26x801x394"
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/dynamic_links/treatment_plans

Arguments

Returns a redirect_url for a draft treatment. It will optionally find or create a patient for use in the treatment plan.

You must have the patients:write OAuth scope if the request you make creates a patient. To access the endpoint you must also have the clinic:write OAuth scope.

Example Request

  
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 $'{
  "patient": {
    "email": "johndoe@fakemail.com"
  },
  "treatment_plan": {
    "practitioner_id": "x1x0196x-5615-4874-xxx4-48x459180x09"
  }
}'

Example Response

  
{
  "dynamic_links": {
    "redirect_url": "https://api-us-snd.fullscript.io/p/treatment_plans/101010/edit",
    "treatment_plan": {
      "id": "x1x01x6x-5615-4874-xxx4-48x459180x09",
      "state": "draft",
      "available_at": null
    },
    "patient": {
      "id": "x1x0196x-5615-4874-xxe4-48x459180x09",
      "first_name": "Example",
      "last_name": "Patient",
      "email": "johndoe@fakemail.com",
      "date_of_birth": null,
      "gender": null,
      "discount": 0,
      "total_discount": 0,
      "mobile_number": "",
      "text_message_notification": 0
    }
  }
}

HTTP Request

POST https://api-us-snd.fullscript.io/api/clinic/dynamic_links/treatment_plans

Arguments

Request IDs

Example

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

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.

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

Attributes

Arguments

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

Upgrading

Upgrading from Version 1 to Version 2 can be done on an endpoint-by-endpoint basis. V1 is soft-deprecated, which means that no new features are going to be added. However, you can continue to use V1 endpoints for as long as you want. Documentation for V1 can be found on swaggerhub.

However, if you are running an older version and want to take advantage of new features and faster response times, then consider upgrading! Going from V1 to V2 is fairly straightforward and you can start using V2 features by requesting the endpoints listed in this documentation.

To see which version you are on, or if you wish to upgrade your patch_version please see the documentation for the Versions endpoint.

Catalog

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.

Attributes

List all allergens

This resource allows you to list all allergens.

Example Request

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

Example Response

  
{
  "allergens": [
    {
      "id": "x5x447x4-x904-4060-83xx-26x5xx9819x7",
      "name": "Sugar Free"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/allergens

Arguments

Retrieve an allergen

Retrieves details for an existing allergen.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/catalog/allergens/x5x447x4-x904-4060-83xx-26x5xx9819x7" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "allergen": {
    "id": "x5x447x4-x904-4060-83xx-26x5xx9819x7",
    "name": "Sugar Free"
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/allergens/:id

Arguments

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.

Attributes

List all brands

This resource allows you to list all brands.

Example Request

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

Example Response

  
{
  "brands": [
    {
      "id": "x0x50x8x-711x-43xx-85xx-5xx80365xxxx",
      "name": "BioBrand",
      "prefix": "BIO",
      "status": "available"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/brands

Arguments

Retrieve a brand

Retrieves details for an existing brand.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/catalog/brands/x0x50x8x-711x-43xx-85xx-5xx80365xxxx" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "brand": {
    "id": "x0x50x8x-711x-43xx-85xx-5xx80365xxxx",
    "name": "BioBrand",
    "prefix": "BIO",
    "status": "unavailable"
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/brands/:id

Arguments

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.

Attributes

List all Ingredients

This resource allows you to list all ingredients.

Example Request

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

Example Response

  
{
  "ingredients": [
    {
      "id": "x5x447x4-x904-4060-83xx-26x5xx9819x7",
      "name": "Vitamin A"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/ingredients

Arguments

Retrieve an ingredient

Retrieves details for an existing ingredient.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/catalog/ingredients/x5x447x4-x904-4060-83xx-26x5xx9819x7" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "ingredient": {
    "id": "x5x447x4-x904-4060-83xx-26x5xx9819x7",
    "name": "Vitamin A"
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/ingredients/:id

Arguments

Practitioner Types

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

Attributes

List all practitioner types

This resource allows you to list all practitioner types.

Example Request

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

Example Response

  
{
  "practitioner_types": [
    {
      "id": "xx55x681-5340-425x-x212-4954xxx92x7x",
      "code": "ND",
      "description": "Naturopathic Doctor"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/practitioner_types

Arguments

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.

Attributes

List all products

This resource allows you to list all products.

Example Request

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

Example Response

  
{
  "products": [
    {
      "id": "113741x6-224x-4xx8-xx5x-80629x155192",
      "name": "Vitamin C",
      "brand": {
        "id": "x0x50x8x-711x-43xx-85xx-5xx80365xxxx",
        "name": "BioBrand",
        "prefix": "BIO"
      },
      "primary_variant": {
        "id": "xx2688x2-4303-4278-xx73-x7083x6146x2",
        "sku": "819d1ab3abc0a21cffd798ec925ba50d",
        "primary": true,
        "units": null,
        "unit_of_measure": null,
        "availability": "n/a",
        "status": null,
        "upc": null,
        "msrp": "19.99",
        "supplier_sku": null,
        "image_url_small": "/assets/noimage/product.png",
        "image_url_medium": "/assets/noimage/product.png",
        "image_url_large": "/assets/noimage/product.png"
      },
      "variant_count": 1,
      "status": "unavailable"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/products

Arguments

Retrieve a product

Retrieves an existing product.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/catalog/products/113741x6-224x-4xx8-xx5x-80629x155192" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "product": {
    "id": "113741x6-224x-4xx8-xx5x-80629x155192",
    "name": "Vitamin C",
    "description_html": "Easy to swallow vitamin c capsules.",
    "brand": {
      "id": "x0x50x8x-711x-43xx-85xx-5xx80365xxxx",
      "name": "BioBrand",
      "prefix": "BIO"
    },
    "variants": [
      {
        "id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
        "sku": "20xx9193488",
        "primary": true,
        "units": null,
        "unit_of_measure": null,
        "availability": "In Stock",
        "status": "available",
        "upc": null,
        "msrp": "19.99",
        "supplier_sku": null
      }
    ],
    "dosage": {
      "recommended_amount": "10-60",
      "recommended_frequency": "four times per day",
      "recommended_duration": "as needed",
      "format": "drop",
      "additional_info": "with meals"
    }
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/products/:id

Arguments

Search for products

This resource allows you to search for products using Fullscript's elasticsearch 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

Example Request

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

Example Response

  
{
  "products": [
    {
      "id": "113741x6-224x-4xx8-xx5x-80629x155192",
      "name": "Vitamin C",
      "brand": {
        "id": "x0x50x8x-711x-43xx-85xx-5xx80365xxxx",
        "name": "BioBrand",
        "prefix": "BIO"
      },
      "primary_variant": {
        "id": "xx2688x2-4303-4278-xx73-x7083x6146x2",
        "sku": "819d1ab3abc0a21cffd798ec925ba50d",
        "primary": true,
        "units": null,
        "unit_of_measure": null,
        "availability": "In Stock",
        "status": "available",
        "upc": null,
        "msrp": "19.99",
        "supplier_sku": null,
        "image_url_small": "/assets/noimage/product.png",
        "image_url_medium": "/assets/noimage/product.png",
        "image_url_large": "/assets/noimage/product.png"
      },
      "variant_count": 1,
      "status": "available"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/search/products

Arguments

List similar products

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.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/catalog/products/113741x6-224x-4xx8-xx5x-80629x155192/similar" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "products": [
    {
      "id": "x1x50x8x-711x-43xx-85xx-5xx80365xxxx",
      "name": "Vitamin C plus",
      "brand": {
        "id": "x0x50x8x-711x-43xx-85xx-5xx80365xxxx",
        "name": "BioBrand",
        "prefix": "BIO"
      },
      "primary_variant": {
        "id": "xx2688x2-4303-4278-xx73-x7083x6146x2",
        "sku": "819d1ab3abc0a21cffd798ec925ba50d",
        "primary": true,
        "units": null,
        "unit_of_measure": null,
        "availability": "n/a",
        "status": null,
        "upc": null,
        "msrp": "19.99",
        "supplier_sku": null,
        "image_url_small": "/assets/noimage/product.png",
        "image_url_medium": "/assets/noimage/product.png",
        "image_url_large": "/assets/noimage/product.png"
      },
      "variant_count": 1,
      "status": "unavailable"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/products/:product_id/similar

Arguments

Similar Products

This endpoint allows you to list similar products that have been curated by Fullscript's licensed health professionals.

List similar products

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.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/catalog/products/113741x6-224x-4xx8-xx5x-80629x155192/similar" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "products": [
    {
      "id": "x1x50x8x-711x-43xx-85xx-5xx80365xxxx",
      "name": "Vitamin C plus",
      "brand": {
        "id": "x0x50x8x-711x-43xx-85xx-5xx80365xxxx",
        "name": "BioBrand",
        "prefix": "BIO"
      },
      "primary_variant": {
        "id": "xx2688x2-4303-4278-xx73-x7083x6146x2",
        "sku": "819d1ab3abc0a21cffd798ec925ba50d",
        "primary": true,
        "units": null,
        "unit_of_measure": null,
        "availability": "n/a",
        "status": null,
        "upc": null,
        "msrp": "19.99",
        "supplier_sku": null,
        "image_url_small": "/assets/noimage/product.png",
        "image_url_medium": "/assets/noimage/product.png",
        "image_url_large": "/assets/noimage/product.png"
      },
      "variant_count": 1,
      "status": "unavailable"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/products/:product_id/similar

Arguments

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.

Attributes

List all supplement types

This resource allows you to list all supplement types.

Example Request

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

Example Response

  
{
  "supplement_types": [
    {
      "id": "x5x447x4-x904-4060-83xx-26x5xx9819x7",
      "name": "vitamins"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/supplement_types

Arguments

Retrieve a supplement type

Retrieves details for an existing supplement type.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/catalog/supplement_types/x5x447x4-x904-4060-83xx-26x5xx9819x7" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "supplement_type": {
    "id": "x5x447x4-x904-4060-83xx-26x5xx9819x7",
    "name": "vitamins"
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/supplement_types/:id

Arguments

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.

Attributes

List all third party certifications

This resource allows you to list all third party certifications.

Example Request

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

Example Response

  
{
  "third_party_certifications": [
    {
      "id": "x5x447x4-x904-4060-83xx-26x5xx9819x7",
      "name": "Certified Halal"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/third_party_certifications

Arguments

Retrieve a third party certification

Retrieves details for an existing third party certification.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/catalog/third_party_certifications/x5x447x4-x904-4060-83xx-26x5xx9819x7" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "third_party_certification": {
    "id": "x5x447x4-x904-4060-83xx-26x5xx9819x7",
    "name": "Certified Halal"
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/third_party_certifications/:id

Arguments

Variants

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

Attributes

Retrieve a variant

Retrieves an existing variant.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/catalog/variants/xx2688x2-4303-4278-xx73-x7083x6146x1" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "variant": {
    "id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
    "sku": "819d1ab3abc0a21cffd798ec925ba50c",
    "primary": true,
    "units": null,
    "unit_of_measure": null,
    "availability": "In Stock",
    "status": "available",
    "upc": null,
    "msrp": "19.99",
    "supplier_sku": null,
    "image_url_small": "/assets/noimage/product.png",
    "image_url_medium": "/assets/noimage/product.png",
    "image_url_large": "/assets/noimage/product.png",
    "product": {
      "id": "113741x6-224x-4xx8-xx5x-80629x155192",
      "name": "Vitamin C",
      "brand": {
        "id": "x0x50x8x-711x-43xx-85xx-5xx80365xxxx",
        "name": "BioBrand",
        "prefix": "BIO"
      }
    }
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/catalog/variants/:id

Arguments

Clinic

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

Attributes

Retrieve a clinic

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

Example Request

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

Example Response

  
{
  "clinic": {
    "id": "xx7x357x-9x36-xxxx-x553-7x3xx398xxx",
    "name": "Dr. Example's Clinic",
    "patient_count": 0,
    "practitioner_count": 1,
    "discount": 0,
    "dispensary_url": "https://api-us-snd.fullscript.io/login/drexamplesclinic",
    "integration_id": "x1x0196x-5615-4874-xxx4-48x459180x09",
    "integration_activated_at": "2018-10-10T04:00:00.000Z"
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic

Arguments

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.

Attributes

List All Patient Addresses

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

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/patients/x1x0196x-5615-4874-xxe4-48x459180x09/addresses" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "addresses": [
    {
      "id": "c7323855-3e77-4829-b1ec-83cd14e09ea2",
      "address1": "8445 E. Hartford Dr.",
      "address2": null,
      "zipcode": "85255",
      "city": "Scottsdale",
      "state": "AZ",
      "country": "US"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/patients/:patient_id/addresses

Arguments

Categories

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

Attributes

List all categories

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

Example Request

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

Example Response

  
{
  "categories": [
    {
      "id": "x3x0196x-5615-4874-xxx4-48x459180x09",
      "name": "Allergy Relief"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/categories

Arguments

Retrieve a Category

Retrieves an existing Category.

Example Request

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

Example Response

  
{
  "category": {
    "id": "x3x0196x-5615-4874-xxx4-48x459180x09",
    "name": "Allergy Relief",
    "product_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/categories/:id

Arguments

List all category products

This resource allows you to list all of a category's products.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/categories/x3x0196x-5615-4874-xxx4-48x459180x09/products" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "products": [
    {
      "id": "113741x6-224x-4xx8-xx5x-80629x155192",
      "name": "Vitamin C",
      "brand": {
        "id": "x0x50x8x-711x-43xx-85xx-5xx80365xxxx",
        "name": "BioBrand",
        "prefix": "BIO"
      },
      "primary_variant": {
        "id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
        "sku": "ABC",
        "primary": true,
        "units": null,
        "unit_of_measure": null,
        "availability": "n/a",
        "status": null,
        "upc": null,
        "msrp": "19.99",
        "supplier_sku": null,
        "image_url_small": "/assets/noimage/product.png",
        "image_url_medium": "/assets/noimage/product.png",
        "image_url_large": "/assets/noimage/product.png"
      },
      "variant_count": 1,
      "status": "unavailable"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/categories/:category_id/products

Arguments

Orders

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

Attributes

List all patient orders

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

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/patients/x1x0196x-5615-4874-xxe4-48x459180x09/orders" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "orders": [
    {
      "id": "391xx4xx-67x5-44x2-8x2x-8886x20x083x",
      "order_number": "R000000000",
      "completed_at": "2018-03-02T13:26:02.000-05:00",
      "treatment_plan_ids": [
        "xx45x0xx-x840-41xx-9922-98xx6001507x"
      ],
      "variant_ids": [
        "xx2688x2-4303-4278-xx73-x7083x6146x1"
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/patients/:patient_id/orders

Arguments

Retrieve an Order

Retrieves an existing Order.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/orders/391xx4xx-67x5-44x2-8x2x-8886x20x083x" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "order": {
    "id": "391xx4xx-67x5-44x2-8x2x-8886x20x083x",
    "order_number": "R000000000",
    "completed_at": "2018-03-02T13:26:02.000-05:00",
    "treatment_plan_ids": [
      "xx45x0xx-x840-41xx-9922-98xx6001507x"
    ],
    "patient_id": "x1x0196x-5615-4874-xxe4-48x459180x09",
    "item_total": "59.97",
    "msrp_total": "59.97",
    "payment_total": "64.96",
    "line_items": [
      {
        "variant_id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
        "quantity": 3
      }
    ]
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/orders/:id

Arguments

List all orders

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

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/orders?patient_id=x1x0196x-5615-4874-xxe4-48x459180x09&completed_at=>2017-01-01" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "orders": [
    {
      "id": "391xx4xx-67x5-44x2-8x2x-8886x20x083x",
      "order_number": "R000000000",
      "completed_at": "2018-03-02T13:26:02.000-05:00",
      "treatment_plan_ids": [
        "xx45x0xx-x840-41xx-9922-98xx6001507x"
      ],
      "variant_ids": [
        "xx2688x2-4303-4278-xx73-x7083x6146x1"
      ],
      "patient_id": "x1x0196x-5615-4874-xxe4-48x459180x09"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/orders

Arguments

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.

Attributes

List all patients

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

Example Request

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

Example Response

  
{
  "patients": [
    {
      "id": "x1x0196x-5615-4874-xxe4-48x459180x09",
      "first_name": "Example",
      "last_name": "Patient",
      "email": "patient@example.com"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/patients

Arguments

Retrieve a patient

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

Example Request

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

Example Response

  
{
  "patient": {
    "id": "x1x0196x-5615-4874-xxe4-48x459180x09",
    "first_name": "Example",
    "last_name": "Patient",
    "email": "patient@example.com",
    "date_of_birth": null,
    "gender": "female",
    "discount": 0,
    "total_discount": 0,
    "mobile_number": null,
    "text_message_notification": true,
    "metadata": {
      "id": "9999-9999-9999"
    }
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/patients/:id

Arguments

Create a patient

Creates a new patient

Example Request

  
curl -X "POST" "https://api-us-snd.fullscript.io/api/clinic/patients" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \
  -d $'{
  "first_name": "Example",
  "last_name": "Patient",
  "email": "example_patient@fullscript.com",
  "date_of_birth": "1977-01-12",
  "mobile_number": "+12223334444",
  "discount": "10",
  "gender": "female",
  "send_welcome_email": "false",
  "metadata": {
    "id": "9999-9999-9999"
  }
}'

Example Response

  
{
  "patient": {
    "id": "x1x0196x-5615-4874-xxe4-48x459180x09",
    "first_name": "Example",
    "last_name": "Patient",
    "email": "example_patient@fullscript.com",
    "date_of_birth": "1977-01-12",
    "gender": "female",
    "discount": 10,
    "total_discount": 10,
    "mobile_number": "+12223334444",
    "text_message_notification": true,
    "metadata": {
      "id": "9999-9999-9999"
    }
  }
}

HTTP Request

POST https://api-us-snd.fullscript.io/api/clinic/patients

Arguments

Update a patient

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

Example Request

  
curl -X "PATCH" "https://api-us-snd.fullscript.io/api/clinic/patients/x1x0196x-5615-4874-xxe4-48x459180x09" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \
  -d $'{
  "first_name": "Ben",
  "last_name": "Peters",
  "metadata": {
    "id": "9999-9999-9999"
  }
}'

Example Response

  
{
  "patient": {
    "id": "x1x0196x-5615-4874-xxe4-48x459180x09",
    "first_name": "Ben",
    "last_name": "Peters",
    "email": "patient@example.com",
    "date_of_birth": null,
    "gender": "female",
    "discount": 0,
    "total_discount": 0,
    "mobile_number": null,
    "text_message_notification": true,
    "metadata": {
      "id": "9999-9999-9999"
    }
  }
}

HTTP Request

PATCH https://api-us-snd.fullscript.io/api/clinic/patients/:id

Arguments

Search for patients

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

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/search/patients?query=patient@example.com" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "patients": [
    {
      "id": "x1x0196x-5615-4874-xxe4-48x459180x09",
      "first_name": "Example",
      "last_name": "Patient",
      "email": "patient@example.com"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/search/patients

Arguments

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.

Attributes

List all practitioners

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

Example Request

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

Example Response

  
{
  "practitioners": [
    {
      "id": "8xx00x67-9684-4679-8x79-xx5fxx12327x",
      "first_name": "Doctor",
      "last_name": "Example",
      "email": "the_doctor@example.com",
      "practitioner_type_id": "xx55x681-5340-425x-x212-4954xxx92x7x",
      "metadata": {
        "id": "9999-9999-9999"
      }
    },
    {
      "id": "x1x0196x-5615-4874-xxx4-48x459180x09",
      "first_name": "Example",
      "last_name": "Practitioner",
      "email": "practitioner@example.com",
      "practitioner_type_id": "xx55x681-5340-425x-x212-4954xxx92x7x",
      "metadata": {
        "id": null
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 2
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/practitioners

Arguments

Retrieve a practitioner

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

Example Request

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

Example Response

  
{
  "practitioner": {
    "id": "8xx00x67-9684-4679-8x79-xx5fxx12327x",
    "first_name": "Doctor",
    "last_name": "Example",
    "email": "the_doctor@example.com",
    "practitioner_type_id": "xx55x681-5340-425x-x212-4954xxx92x7x",
    "metadata": {
      "id": "9999-9999-9999"
    }
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/practitioners/:id

Arguments

Create a practitioner

Creates a new practitioner

Example Request

  
curl -X "POST" "https://api-us-snd.fullscript.io/api/clinic/practitioners" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \
  -d $'{
  "first_name": "Another",
  "last_name": "Doctor",
  "email": "another_doctor@example.com",
  "practitioner_type_id": "xx55x681-5340-425x-x212-4954xxx92x7x",
  "metadata": {
    "id": "123"
  }
}'

Example Response

  
{
  "practitioner": {
    "id": "xx9598xx-x765-xxxx-81x8-847050x15x85",
    "first_name": "Another",
    "last_name": "Doctor",
    "email": "another_doctor@example.com",
    "practitioner_type_id": "xx55x681-5340-425x-x212-4954xxx92x7x",
    "metadata": {
      "id": "123"
    }
  }
}

HTTP Request

POST https://api-us-snd.fullscript.io/api/clinic/practitioners

Arguments

Update a practitioner

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

Example Request

  
curl -X "PATCH" "https://api-us-snd.fullscript.io/api/clinic/practitioners/8xx00x67-9684-4679-8x79-xx5fxx12327x" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \
  -d $'{
  "first_name": "Doctor",
  "last_name": "Smith",
  "email": "dr_smith99@example.com",
  "metadata": {
    "id": "123"
  }
}'

Example Response

  
{
  "practitioner": {
    "id": "8xx00x67-9684-4679-8x79-xx5fxx12327x",
    "first_name": "Doctor",
    "last_name": "Smith",
    "email": "dr_smith99@example.com",
    "practitioner_type_id": "xx55x681-5340-425x-x212-4954xxx92x7x",
    "metadata": {
      "id": "123"
    }
  }
}

HTTP Request

PATCH https://api-us-snd.fullscript.io/api/clinic/practitioners/:id

Arguments

Protocols

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

Attributes

Retrieve a protocol

Retrieves an existing protocol.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/protocols/2x28xx67-x5xx-408x-8820-x5x00x617148" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "protocol": {
    "id": "2x28xx67-x5xx-408x-8820-x5x00x617148",
    "name": "Cold and Flu Season",
    "current_state": "active",
    "practitioner": {
      "id": "8xx00x67-9684-4679-8x79-xx5fxx12327x"
    },
    "personal_message": "Take with a meal. Not on an empty stomach.",
    "recommendations": [
      {
        "variant_id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
        "refill": false,
        "dosage_amount": "4",
        "dosage_frequency": "three times per day",
        "dosage_duration": null,
        "dosage_permutations": "with food",
        "dosage_format": "capsule",
        "quantity_recommended": 1
      }
    ]
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/protocols/:id

Arguments

List all practitioner protocols

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

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/practitioners/x1x0196x-5615-4874-xxx4-48x459180x09/protocols" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "protocols": [
    {
      "id": "2x28xx67-x5xx-408x-8820-x5x00x617148",
      "name": "Cold and Flu Season",
      "current_state": "active"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/practitioners/:practitioner_id/protocols

Arguments

Templates
Deprecated

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.

Attributes

Retrieve a template
Deprecated

Retrieves an existing template.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/templates/2x28xx67-x5xx-408x-8820-x5x00x617148" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "template": {
    "id": "2x28xx67-x5xx-408x-8820-x5x00x617148",
    "name": "Cold and Flu Season",
    "current_state": "active",
    "practitioner_id": "8xx00x67-9684-4679-8x79-xx5fxx12327x",
    "personal_message": "Take with a meal. Not on an empty stomach.",
    "recommendations": [
      {
        "variant_id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
        "refill": false,
        "dosage_amount": "4",
        "dosage_frequency": "three times per day",
        "dosage_duration": null,
        "dosage_permutations": "with food",
        "dosage_format": "capsule",
        "quantity_recommended": 1
      }
    ]
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/templates/:id

Arguments

List all practitioner templates
Deprecated

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

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/practitioners/x1x0196x-5615-4874-xxx4-48x459180x09/templates" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "templates": [
    {
      "id": "2x28xx67-x5xx-408x-8820-x5x00x617148",
      "name": "Cold and Flu Season",
      "current_state": "active"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/practitioners/:practitioner_id/templates

Arguments

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.

Attributes

List all patient treatment plans

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

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/patients/x1x0196x-5615-4874-xxe4-48x459180x09/treatment_plans" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "treatment_plans": [
    {
      "id": "xx45x0xx-x840-41xx-9922-98xx6001507x",
      "state": "active",
      "patient": {
        "id": "x1x0196x-5615-4874-xxe4-48x459180x09"
      },
      "practitioner": {
        "id": "x1x0196x-5615-4874-xxx4-48x459180x09"
      },
      "available_at": "2018-03-02",
      "created_at": "2020-01-01T05:00:00.000Z",
      "updated_at": "2020-01-01T05:00:00.000Z"
    },
    {
      "id": "x1x01x6x-5615-4874-xxx4-48x459180x09",
      "state": "active",
      "patient": {
        "id": "x1x0196x-5615-4874-xxe4-48x459180x09"
      },
      "practitioner": {
        "id": "x1x0196x-5615-4874-xxx4-48x459180x09"
      },
      "available_at": "2020-01-01",
      "created_at": "2020-01-01T05:00:00.000Z",
      "updated_at": "2020-01-01T05:00:00.000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 2
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/patients/:patient_id/treatment_plans

Arguments

Create a patient treatment plan

Creates a new Treatment Plan for a patient.

Example Request

  
curl -X "POST" "https://api-us-snd.fullscript.io/api/clinic/patients/x1x0196x-5615-4874-xxe4-48x459180x09/treatment_plans" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \
  -d $'{
  "practitioner_id": "x1x0196x-5615-4874-xxx4-48x459180x09",
  "personal_message": "Take with a meal. Not on an empty stomach. Try to take this at the same time every day for best results.",
  "metadata": {
    "id": "123"
  },
  "recommendations": [
    {
      "variant_id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
      "refill": "true",
      "units_to_purchase": "1",
      "dosage": {
        "amount": "1-2",
        "frequency": "once per day",
        "duration": "as needed",
        "format": "capsule",
        "additional_info": "with food"
      }
    }
  ]
}'

Example Response

  
{
  "treatment_plan": {
    "id": "70x0x171-xxxx-4xx8-xxx6-79391x5xx8xx",
    "state": "active",
    "patient": {
      "id": "x1x0196x-5615-4874-xxe4-48x459180x09"
    },
    "practitioner": {
      "id": "x1x0196x-5615-4874-xxx4-48x459180x09"
    },
    "available_at": "2018-04-11",
    "created_at": "2020-01-01T05:00:00.000Z",
    "updated_at": "2020-01-01T05:00:00.000Z",
    "invitation_url": "https://fullscript.io/welcome/drexample/999999xxxxx",
    "recommendations": [
      {
        "variant_id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
        "refill": true,
        "units_to_purchase": 1,
        "dosage": {
          "amount": "1-2",
          "frequency": "once per day",
          "duration": "as needed",
          "format": "capsule",
          "additional_info": "with food"
        }
      }
    ],
    "personal_message": "Take with a meal. Not on an empty stomach. Try to take this at the same time every day for best results.",
    "metadata": {
      "id": "123"
    }
  }
}

HTTP Request

POST https://api-us-snd.fullscript.io/api/clinic/patients/:patient_id/treatment_plans

Arguments

Retrieve a treatment plan

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

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/treatment_plans/xx45x0xx-x840-41xx-9922-98xx6001507x" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "treatment_plan": {
    "id": "xx45x0xx-x840-41xx-9922-98xx6001507x",
    "state": "active",
    "patient": {
      "id": "x1x0196x-5615-4874-xxe4-48x459180x09"
    },
    "practitioner": {
      "id": "x1x0196x-5615-4874-xxx4-48x459180x09"
    },
    "available_at": "2018-03-02",
    "created_at": "2020-01-01T05:00:00.000Z",
    "updated_at": "2020-01-01T05:00:00.000Z",
    "invitation_url": "https://fullscript.io/welcome/drexample/999999xxxxx",
    "recommendations": [
      {
        "variant_id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
        "refill": false,
        "units_to_purchase": 10,
        "dosage": {
          "amount": "1-2",
          "frequency": "once per day",
          "duration": null,
          "format": "capsule",
          "additional_info": "with food"
        }
      }
    ],
    "personal_message": null,
    "metadata": {
      "id": "9999-9999-9999"
    }
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/treatment_plans/:id

Arguments

Update a treatment plan

Updates a Treatment Plan for a patient.

Example Request

  
curl -X "PATCH" "https://api-us-snd.fullscript.io/api/clinic/treatment_plans/xx45x0xx-x840-41xx-9922-98xx6001507x" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX' \
  -d $'{
  "personal_message": "Take with a meal. Not on an empty stomach.",
  "metadata": {
    "id": "9999-9999-9999"
  },
  "recommendations": [
    {
      "variant_id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
      "refill": "true",
      "units_to_purchase": "1",
      "dosage": {
        "amount": "1-2",
        "frequency": "once per day",
        "duration": "as needed",
        "format": "capsule",
        "additional_info": "with food"
      }
    }
  ]
}'

Example Response

  
{
  "treatment_plan": {
    "id": "xx45x0xx-x840-41xx-9922-98xx6001507x",
    "state": "active",
    "patient": {
      "id": "x1x0196x-5615-4874-xxe4-48x459180x09"
    },
    "practitioner": {
      "id": "x1x0196x-5615-4874-xxx4-48x459180x09"
    },
    "available_at": "2018-03-02",
    "created_at": "2020-01-01T05:00:00.000Z",
    "updated_at": "2020-01-01T05:00:00.000Z",
    "invitation_url": "https://fullscript.io/welcome/drexample/999999xxxxx",
    "recommendations": [
      {
        "variant_id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
        "refill": false,
        "units_to_purchase": 1,
        "dosage": {
          "amount": "1-2",
          "frequency": "once per day",
          "duration": "as needed",
          "format": "capsule",
          "additional_info": "with food"
        }
      }
    ],
    "personal_message": "Take with a meal. Not on an empty stomach.",
    "metadata": {
      "id": "9999-9999-9999"
    }
  }
}

HTTP Request

PATCH https://api-us-snd.fullscript.io/api/clinic/treatment_plans/:id

Arguments

Cancel a treatment plan

Cancels an active Treatment Plan for a patient.

Example Request

  
curl -X "PATCH" "https://api-us-snd.fullscript.io/api/clinic/treatment_plans/xx45x0xx-x840-41xx-9922-98xx6001507x/cancel" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "treatment_plan": {
    "id": "xx45x0xx-x840-41xx-9922-98xx6001507x",
    "state": "cancelled",
    "patient": {
      "id": "x1x0196x-5615-4874-xxe4-48x459180x09"
    },
    "practitioner": {
      "id": "x1x0196x-5615-4874-xxx4-48x459180x09"
    },
    "available_at": "2018-03-02",
    "created_at": "2020-01-01T05:00:00.000Z",
    "updated_at": "2020-01-01T05:00:00.000Z",
    "invitation_url": "https://fullscript.io/welcome/drexample/999999xxxxx",
    "recommendations": [

    ],
    "personal_message": null,
    "metadata": {
      "id": null
    }
  }
}

HTTP Request

PATCH https://api-us-snd.fullscript.io/api/clinic/treatment_plans/:treatment_plan_id/cancel

Arguments

Activate a treatment plan

Activates a draft Treatment Plan for a patient.

Example Request

  
curl -X "PATCH" "https://api-us-snd.fullscript.io/api/clinic/treatment_plans/xx45x0xx-x840-41xx-9922-98xx6001507x/activate" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "treatment_plan": {
    "id": "xx45x0xx-x840-41xx-9922-98xx6001507x",
    "state": "active",
    "patient": {
      "id": "x1x0196x-5615-4874-xxe4-48x459180x09"
    },
    "practitioner": {
      "id": "x1x0196x-5615-4874-xxx4-48x459180x09"
    },
    "available_at": "2018-03-02",
    "created_at": "2020-01-01T05:00:00.000Z",
    "updated_at": "2020-01-01T05:00:00.000Z",
    "invitation_url": "https://fullscript.io/welcome/drexample/999999xxxxx",
    "recommendations": [
      {
        "variant_id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
        "refill": false,
        "units_to_purchase": 10,
        "dosage": {
          "amount": "1-2",
          "frequency": "once per day",
          "duration": null,
          "format": "capsule",
          "additional_info": "with food"
        }
      }
    ],
    "personal_message": null,
    "metadata": {
      "id": null
    }
  }
}

HTTP Request

PATCH https://api-us-snd.fullscript.io/api/clinic/treatment_plans/:treatment_plan_id/activate

Arguments

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.

Example Request

  
curl -X "POST" "https://api-us-snd.fullscript.io/api/clinic/treatment_plans/70x0x171-xxxx-4xx8-xxx6-79391x5xx8xx/in_office_checkout" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "in_office_checkout": {
    "url": "https://fullscript.io/o/patients/11/checkout"
  }
}

HTTP Request

POST https://api-us-snd.fullscript.io/api/clinic/treatment_plans/:treatment_plan_id/in_office_checkout

Arguments

Metadata

Metadata allows you to update specific objects in Fullscript with an ID of your choosing. Currently we support updating Patient, Practitioner, 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.

Attributes

Find objects

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

Example Request

  
curl "https://api-us-snd.fullscript.io/api/clinic/metadata?id=9999-9999-9999&type=patient" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "metadata": [
    {
      "id": "9999-9999-9999",
      "type": "patient",
      "data": {
        "id": "x1x0196x-5615-4874-xxe4-48x459180x09",
        "first_name": "Example",
        "last_name": "Patient",
        "email": "patient@example.com",
        "date_of_birth": null,
        "gender": null,
        "discount": 0,
        "total_discount": 0,
        "mobile_number": null,
        "text_message_notification": true,
        "metadata": {
          "id": "9999-9999-9999"
        }
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/clinic/metadata

Arguments

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

Attributes

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.

Example Request

  
curl "https://api-us-snd.fullscript.io/api/events/99x67086-x10x-11x8-8x83-186590xxx6x1" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXX'

Example Response

  
{
  "event": {
    "id": "99x67086-x10x-11x8-8x83-186590xxx6x1",
    "type": "treatment_plan.created",
    "created_at": "2018-10-17T04:00:00.000Z",
    "clinic_id": "xx7x357x-9x36-xxxx-x553-7x3xx398xxx",
    "data": {
      "treatment_plan": {
        "id": "99x67086-x10x-11x8-8x83-186590xxx6x1",
        "state": "active",
        "patient": {
          "id": "99x67086-x10x-11x8-8x83-186590xxx6x1"
        },
        "practitioner": {
          "id": "99x67086-x10x-11x8-8x83-186590xxx6x1"
        },
        "available_at": "2018-10-16T04:00:00.000Z",
        "recommendations": [
          {
            "variant_id": "xx2688x2-4303-4278-xx73-x7083x6146x1",
            "refill": false,
            "units_to_purchase": 10,
            "dosage": {
              "recommended_amount": "1-2",
              "recommended_frequency": "once per day",
              "recommended_duration": null,
              "format": "capsule",
              "additional_info": "with food"
            }
          }
        ]
      }
    }
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/events/:id

Arguments

List All ClinicKey Events

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

Example Request

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

Example Response

  
{
  "events": [
    {
      "id": "3x302630-xx40-11x8-xxx3-186590xxx6b1",
      "type": "clinic_key.activated",
      "created_at": "2018-10-16T04:00:00.000Z",
      "clinic_id": "xx7x357x-9x36-xxxx-x553-7x3xx398xxx"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/events/clinic_keys

Arguments

List All Patient Events

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

Example Request

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

Example Response

  
{
  "events": [
    {
      "id": "84562974-4x0x-1128-3x3x-1x86x5x836x2",
      "type": "patient.created",
      "created_at": "2018-10-16T04:00:00.000Z",
      "clinic_id": "xx7x357x-9x36-xxxx-x553-7x3xx398xxx"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/events/patients

Arguments

List All TreatmentPlan Events

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

Example Request

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

Example Response

  
{
  "events": [
    {
      "id": "58xx7520-xx46-11x8-x099-186590xxxxx1",
      "type": "treatment_plan.recommendation.updated",
      "created_at": "2018-10-16T04:00:00.000Z",
      "clinic_id": "xx7x357x-9x36-xxxx-x553-7x3xx398xxx"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/events/treatment_plans

Arguments

List All Order Events

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

Example Request

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

Example Response

  
{
  "events": [
    {
      "id": "84562974-4x0x-1128-3x3x-1x86x5x836x2",
      "type": "order.placed",
      "created_at": "2018-10-16T04:00:00.000Z",
      "clinic_id": "xx7x357x-9x36-xxxx-x553-7x3xx398xxx"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/events/orders

Arguments

List All Product Events

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

Example Request

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

Example Response

  
{
  "events": [
    {
      "id": "84562974-4x0x-1128-3x3x-1x86x5x836x2",
      "type": "product.created",
      "created_at": "2018-10-16T04:00:00.000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/events/products

Arguments

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 App 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 App. 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 App). 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 App 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:

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:

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

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.

Attributes

List All Webhook Deliveries

This endpoint lists all webhook_deliveries from the last 30 days.

Example Request

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

Example Response

  
{
  "webhook_deliveries": [
    {
      "id": "3x0x2147-6x82-49xx-9x59-621xx87x40x2",
      "attempt_number": 1,
      "attempted_at": "2018-10-16T04:01:00.000Z",
      "previous_attempt_at": null,
      "next_attempt_at": null,
      "successfully_delivered": false,
      "response_body": "{\"challenge\"=>\"my-secret-challenge-token\"}",
      "response_header": "{\"Content-type\"=>\"application/json\"}",
      "response_status": 200,
      "response_ip_address": "127.0.0.1",
      "response_errors": null,
      "event_payload": {
        "event": {
          "id": "x5xxxxx8-92x7-4xxx-9x0x-345x404x94x1",
          "type": "patient.updated",
          "created_at": "2018-10-16T04:00:00.000Z",
          "clinic_id": "xx7x357x-9x36-xxxx-x553-7x3xx398xxx",
          "data": {
            "patient": {
              "id": "x1x0196x-5615-4874-xxe4-48x459180x09",
              "first_name": "Example",
              "last_name": "Patient",
              "email": "patient@example.com",
              "date_of_birth": null,
              "gender": null,
              "discount": 0,
              "total_discount": 0,
              "mobile_number": null,
              "text_message_notification": true
            }
          },
          "integration_id": "x1x27xxx-x9x9-49x6-xx62-107x7x051874"
        }
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

HTTP Request

GET https://api-us-snd.fullscript.io/api/webhooks/deliveries

Arguments