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.
- Practitioners are asked to grant access to their Fullscript account
- The practitioner is redirected back to your site by Fullscript
- 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
-
access_token
The secret token that can be used when making a request to an authorized resource.
-
token_type
The type of token. Default is
Bearer
. -
expires_in
Time (in seconds) when the token will expire. This is calculated from the token's created_at timestamp. All tokens expire in 2 hours.
-
refresh_token
A code that can be used to generate a fresh token so that Practitioners don't need to re-authorize when their token has expired.
-
resource_owner
Information about the resource who has granted access
-
created_at
Timestamp (in utc) when the token was created.
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
-
client_id required
Unique ID of the OAuth application.
-
client_secret required
Secret token for the OAuth application.
-
code required
The temporary code that is used to exchange for an OAuth token. (Required when using the
authorization_code
grant type.) -
refresh_token
The refresh token that can be used to exchange an expired token for a fresh one. (Required when using the
refresh_token
grant type.) -
redirect_uri required
The
redirect_uri
that matches theredirect_uri
of the application. -
grant_type required
The type of OAuth grant you are requesting. Possible options are
authorization_code
if you're getting the token for the first time. Orrefresh_token
if you're trying to refresh a stale token.
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
-
client_id required
Unique ID of the OAuth application.
-
client_secret required
Secret token for the OAuth application.
-
token required
OAuth token to be revoked.
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
-
redirect_url
Absolute url for a treatment plan in fullscript.
-
treatment_plan
Treatment plan information for dynamic link.
-
patient
Patient information for dynamic_link.
Retrieve a Treatment Plan Link
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
Retrieve a new Treatment Plan link
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
-
No arguments ...
Create a Draft Treatment Plan Link
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
-
treatment_plan required
Treatment plan information for dynamic link.
-
patient
Find or create a Patient.
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
-
current_page
The current page number of the API response.
-
next_page
Then next page number (if available).
-
prev_page
The previous page number (if available).
-
total_pages
Total number of pages that are available in the API response.
-
total_count
Total number of records available in the resource.
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).
- 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
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
-
No 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
-
id
Unique identifier of the brand.
-
name
Commercial name of the brand.
-
status
The current state of a brand's products which return two possible values:
available
andunavailable
.available
means that this brand has some products that are in-stock and available to be ordered.unavailable
means that this brand does not have any products in-stock. Note that this does not take into account product segmentation (where only certain practitioners have access to some brands) Please use the product search endpoint for tailored products that are available to your practitioner. -
prefix
Unique prefix for the brand.
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
-
available
Takes an argument of
true
to return brands that have available products. -
clinic_permitted
Takes an argument of
true
to return brands the current clinic has access to.
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
-
No 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
-
id
Unique identifier of the practitioner type.
-
code
Short code for the practitioner type.
-
description
Description for the practitioner type.
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
-
No 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
-
id
Unique identifier of the product.
-
name
Name of the product.
-
status
Status of the Product. Has 3 possible values. If any of the product variants are available, then status is
available
. If none of the product variants are available, but any 1 of the product variants is backordered then status isbackordered
. If none of the product variants are available or backordered then status isunavailable
. -
variant_count
The number of variants that exist for this product.
-
brand
Brand information for the product.
-
description_html
HTML description of the product (if available).
-
variants
All available variants for the product.
-
dosage
Dosage information for the product.
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
-
No 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
-
query
Search for products matching a query string.
-
allergen_ids
Provide an array of allergen ids to filter results.
-
brand_id
Search for products by brand_id.
-
ingredient_ids
Provide an array of ingredient ids to filter results.
-
supplement_type_ids
Provide an array of supplement type ids to filter results.
-
third_party_certification_ids
Provide an array of third party certification ids to filter results.
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
-
No 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
-
No 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
-
id
Unique identifier for the variant.
-
sku
Unique SKU for the variant used by Fullscript.
-
units
Number of units in the variant (e.g. 90 capsules or 250 mL).
-
unit_of_measure
Units of measure (e.g. capsules).
-
upc
UPC, EAN-13, or scannable bar code.
-
msrp
The MSRP (suggested selling price) for the product. (e.g. 19.99)
-
supplier_sku
The Supplier SKU.
-
status
Returns the current status of the variant. (e.g. available, discontinued, backordered, unavailable, or vendor backorder)
-
availability
Returns the availability of the variant. (e.g. In Stock)
-
primary
Reveals whether the variant is the primary (main one used for display purposes) or not.
-
image_url_small
Thumbnail-sized image url of the variant.
-
image_url_medium
Medium-sized image url of the variant.
-
image_url_large
Large-sized image url of the variant.
-
product
The variant's product.
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
-
id
Unique identifier of the clinic.
-
name
Name of the clinic.
-
patient_count
Number of patients that belong to the clinic.
-
practitioner_count
Number of practitioners that belong to the clinic.
-
discount
Discount level of the clinic. This discount (in percentage) is the global discount level of the clinic that will be applied to all patient orders (in addition to any patient-level discount).
-
dispensary_url
Patient-facing dispensary url.
-
integration_id
Unique identifier for the clinic's integration.
-
integration_activated_at
Moment in time when a clinic's integration is considered active. This happens on the very first request made using a valid
X-FS-Clinic-Key
.
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
-
No 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
-
id
Unique identifier of the address.
-
address1
Street Address of the address.
-
address2
Apartment/Floor/Suite or Building # of the address.
-
zipcode
Zipcode (US) or Postal Code (Canada) of the address.
-
city
City of the address.
-
state
State (US) or Province (Canada) of the address.
-
country
The country of the address.
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
-
id
Unique identifier of the category.
-
name
Name of the category.
-
product_count
Number of products in a category.
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
-
No 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
-
id
Unique identifier of the order.
-
order_number
Public order ID.
-
completed_at
Timestamp for when the order was completed.
-
msrp_total
Current total amount of an order before taxes / shipping costs.
-
item_total
Current total amount of an order before taxes / shipping costs but including any patient or clinic discounts (if applied).
-
payment_total
Current total amount of an order including any taxes, shipping costs, and refunds.
-
variant_ids
Unique identifiers for the order's variants.
-
treatment_plan_ids
Unique identifiers for the order's treatment plans.
-
line_items
Individual line items on an order.
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
-
patient_id
Filter orders by
patient_id
. -
treatment_plan_id
Filter orders by
treatment_plan_id
. -
completed_at
Filter orders by
completed_at
. The date must be formatted as followsyyyy-mm-dd
. -
order_number
Filter orders by
order_number
. -
sort_by
Accepts one of the following arguments:
patient_id
,treatment_plan_id
,completed_at
andorder_number
. -
order_by
Ordering defaults to
ASC
and can take an argument ofASC
orDESC
.
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
-
id
Unique identifier of the patient.
-
first_name
First name of the patient.
-
last_name
Last name of the patient.
-
email
Unique email of the patient.
-
date_of_birth
Date of birth of the patient in the format
yyyy-mm-dd
. -
gender
Gender of the patient. Valid options are 'male', 'female', or 'x'.
-
discount
Patient discount level (in percentage). This discount does not include the clinic discount. This discount, in addition to any clinic discount, will be applied to all of the patient's orders.
-
total_discount
Total patient discount level (in percentage). This discount includes the clinic discount and the patient discount. This discount is applied to all of the patient's orders.
-
mobile_number
Valid phone number for a patient.
-
text_message_notification
true
orfalse
of whether the patient has elected to receive text message notifications from Fullscript. -
metadata
Metadata that has been attached to the patient.
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
-
No 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
-
email required
Unique Email for the Patient
-
first_name required
Patient's first name
-
last_name required
Patient's last name
-
date_of_birth
Patient's date of birth in the format
yyyy-mm-dd
-
gender
Gender of the patient. Valid options are 'male', 'female', or 'x'.
-
mobile_number
Patient's mobile number in the format
+12223334444
-
send_welcome_email
Sends a welcome email to the patient upon successful creation. Defaults to true.
-
discount
Patient discount level (in percentage). This discount does not include the clinic discount. Defaults to 0.
-
metadata
Metadata to be attached to the patient.
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
-
email
Unique Email for the Patient
-
first_name
Patient's first name
-
last_name
Patient's last name
-
date_of_birth
Patient's date of birth in the format
yyyy-mm-dd
-
gender
Gender of the patient. Valid options are 'male', 'female', or 'x'.
-
mobile_number
Patient's mobile number in the format
+12223334444
-
discount
Patient discount level (in percentage). This discount does not include the clinic discount. Defaults to 0.
-
metadata
Metadata to be attached to the patient.
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
-
id
Unique identifier of the practitioner.
-
first_name
First name of the practitioner.
-
last_name
Last name of the practitioner.
-
email
Unique email of the practitioner. Patient emails in Fullscript are unique.
-
metadata
Metadata that has been attached to the practitioner.
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
-
No 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
-
practitioner_type_id required
Unique Identifier for the Practitioner's Type
-
email required
Unique Email for the Practitioner
-
first_name required
Practitioner's first name
-
last_name required
Practitioner's last name
-
metadata
Metadata to be attached to the practitioner.
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
-
practitioner_id required
Unique Identifier for the Practitioner
-
practitioner_type_id
Unique Identifier for the Practitioner's Type
-
email
Unique Email for the Practitioner
-
first_name
Practitioner's first name
-
last_name
Practitioner's last name
-
metadata
Metadata to be attached to the practitioner.
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
-
id
Unique identifier of the protocol.
-
name
Name of the protocol.
-
current_state
The state of the protocol, can be draft, active or cancelled.
-
practitioner
Practitioner object.
-
personal_message
A personal message that a practitioner can attach to the protocol.
-
recommendations
Rx plan for a product.
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
-
practitioner_id required
Unique ID for the Practitioner
-
current_state
Takes an argument of
active
,draft
orcancelled
to returnactive
,draft
orcancelled
protocols. -
sort_by
Accepts one of the following arguments:
name
orcurrent_state
. -
order_by
Ordering defaults to
ASC
and can take an argument ofASC
orDESC
.
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
-
id
Unique identifier of the template.
-
name
Name of the template.
-
current_state
The state of the template, can be draft, active or cancelled.
-
practitioner_id
Unique identifier of the practitioner who made the template.
-
personal_message
A personal message that a practitioner can attach to the template.
-
recommendations
Rx plan for a product.
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
-
patient_id
Unique ID for the Patient.
-
practitioner_id
Unique ID for the Practitioner.
-
state
The state of the treatment plan. It has 3 possible values
draft
,active
orcancelled
. -
available_at
The date when the treatment plan was sent to the patient either through an email or text message.
-
created_at
Timestamp (in utc) when the Treatment Plan was created.
-
updated_at
Timestamp (in utc) when the Treatment Plan was updated.
-
invitation_url
Fullscript url for a patient to view their treatment plan.
-
personal_message
A personal message that a practitioner can attach to the treatment plan.
-
recommendations
Rx plan for a product.
-
metadata
Metadata that has been attached to the treatment_plan.
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
-
patient_id required
Unique ID for the Patient
-
sort_by
Accepts one of the following arguments:
created_at
orupdated_at
. -
order_by
Ordering defaults to
ASC
and can take an argument ofASC
orDESC
.
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
-
patient_id required
Unique ID for the Patient.
-
practitioner_id required
Unique ID for the Practitioner.
-
personal_message
A personal message that a practitioner can attach to the treatment plan.
-
state
The state of the treatment plan. Takes an option of
draft
oractive
. Defaults to active if null. The valuedraft
allows to create a draft treatment plan. The valueactive
or null creates an active treatment plan. -
recommendations required
Rx plan for a product.
-
metadata
Metadata to be attached to the treatment_plan.
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
-
treatment_plan_id required
Unique ID for the Treatment plan.
-
personal_message
A personal message that a practitioner can attach to the treatment plan.
-
recommendations required
Rx plan for a product.
-
metadata
Metadata to be attached to the treatment_plan.
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
-
id
Your system's identifier.
-
type
The type of object. Can be one of
patient
,practitioner
, ortreatment_plan
. -
data
The object from the Fullscript system will be populated here.
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
-
id
Your system's identifier.
-
type
The type of object. Can be one of
patient
,practitioner
, ortreatment_plan
.
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
-
id
Unique identifier of the event.
-
type
The type of event that was created.
-
created_at
Timestamp (in utc) when the event was created.
-
clinic_id
Unique identifier of the clinic that this event is scoped to (if applicable).
-
data
The data attribute holds all the information for the event's object (if applicable). For example, when retrieving a
patient.created
event, thedata
attribute will have a complete patient object nested inside.
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.
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 validX-FS-Clinic-Key
—activating the integration.
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
-
created_at
Filter by
created_at
date. The date must be formatted as followsyyyy-mm-dd
. -
event_type
Filter events by
event_type
. -
sort_by
Accepts one of the following arguments:
event_type
created_at
. -
order_by
Ordering defaults to
ASC
and can take an argument ofASC
orDESC
.
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.
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
-
created_at
Filter by
created_at
date. The date must be formatted as followsyyyy-mm-dd
. -
event_type
Filter events by
event_type
. -
sort_by
Accepts one of the following arguments:
event_type
created_at
. -
order_by
Ordering defaults to
ASC
and can take an argument ofASC
orDESC
.
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
treatmen_plan.updated
event happens when a Treatment Plan is updated.A
treatmen_plan.recommendation.updated
event happens when a Treatment Plan's recommendation is updated.
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
-
created_at
Filter by
created_at
date. The date must be formatted as followsyyyy-mm-dd
. -
event_type
Filter events by
event_type
. -
sort_by
Accepts one of the following arguments:
event_type
created_at
. -
order_by
Ordering defaults to
ASC
and can take an argument ofASC
orDESC
.
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.
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
-
created_at
Filter by
created_at
date. The date must be formatted as followsyyyy-mm-dd
. -
event_type
Filter events by
event_type
. -
sort_by
Accepts one of the following arguments:
event_type
created_at
. -
order_by
Ordering defaults to
ASC
and can take an argument ofASC
orDESC
.
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.
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
-
created_at
Filter by
created_at
date. The date must be formatted as followsyyyy-mm-dd
. -
event_type
Filter events by
event_type
. -
sort_by
Accepts one of the following arguments:
event_type
created_at
. -
order_by
Ordering defaults to
ASC
and can take an argument ofASC
orDESC
.
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:
- 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
andsignature
from the header. - Create the
payload
by combining thetimestamp
andrequest_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 thepayload
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.
Attributes
-
id
Unique identifier of the delivery.
-
attempt_number
Number of attempts that were made for this event.
-
attempted_at
Timestamp (in utc) when the delivery was attempted.
-
previous_attempt_at
Timestamp (in utc) when the previous delivery was attempted (if any).
-
next_attempt_at
Timestamp (in utc) when the next delivery attempt was scheduled (if any).
-
successfully_delivered
true
orfalse
of whether the event has been successfully delivered. -
response_body
The response body that we received from your server.
-
response_header
The header that we received from your server.
-
response_status
The http status code that we received from your server.
-
response_ip_address
The IP address that we received from your server.
-
response_errors
Any error messages that we received while attempting to deliver to your server.
-
event_payload
The event object.
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
-
attempted_at
Filter by
attempted_at
date. The date must be formatted as followsyyyy-mm-dd
. -
event_id
Filter webhook deliveries by
event_id
. -
successfully_delivered
Filter webhook deliveries by whether they have been successfully delivered or not. Accepts a string of
true
orfalse
-
sort_by
Accepts one of the following arguments:
event_id
attempted_at
. -
order_by
Ordering defaults to
ASC
and can take an argument ofASC
orDESC
.