# Fullscript API Documentation

> Partner API documentation for Fullscript Embed, Redirect, OAuth, webhooks, events, and REST endpoints. Use the OpenAPI spec for request/response schemas and this index to find guides.

## AI integration quickstart

- [For AI](http://fullscript.dev/docs/getting-started/for-ai/overview): Recommended context, reading order, and copy-paste prompt for LLM sessions
- [Integration environments JSON](http://fullscript.dev/integration-environments.json): Canonical API and OAuth base URLs per region and environment
- [agents.md](http://fullscript.dev/agents.md): Short pointer for AI coding tools
- [llms.txt](http://fullscript.dev/llms.txt): This file

## Machine-readable API spec

- [OpenAPI JSON](https://us.fullscript.com/docs/api/open-api/v1/openapi.json): Complete REST API schema (source of truth for endpoints, parameters, and examples)
- [Technical reference](http://fullscript.dev/technical-reference): Human-readable endpoint docs derived from OpenAPI

## External SDK and assets

- [fullscript-js (GitHub)](https://github.com/Fullscript/fullscript-js): Embed SDK source and releases
- [@fullscript/fullscript-js (npm)](https://www.npmjs.com/package/@fullscript/fullscript-js): Embed SDK package for npm/yarn installs
- [fullscript-js UMD bundle](https://public-assets.fullscript.com/fullscript.js/3.0.1/fullscript-js.umd.min.js): Script tag embed without a bundler

## Getting started

- [Get started with Fullscript APIs](http://fullscript.dev/docs/getting-started): Our goal is to help you with everything you'll need to know when integrating with Fullscript.
- [What is Fullscript?](http://fullscript.dev/docs/getting-started/introduction/what-is-fullscript): Let’s start with a brief overview of Fullscript so you can see how it’s being used and where your integration fits.
- [Integration options](http://fullscript.dev/docs/getting-started/introduction/integration-options): Choose between one of our two integration methods:
- [Sign up for API key](http://fullscript.dev/docs/getting-started/introduction/sign-up-for-api-key): To use the Fullscript APIs you need access to our API Dashboard and developer API keys.
- [For AI](http://fullscript.dev/docs/getting-started/for-ai/overview): Use this page when you (or an AI coding assistant) are integrating with Fullscript APIs. It lists canonical sources, a recommended reading order, and a copy-paste context block you can drop into any L

## How-to guides

- [How-to guides](http://fullscript.dev/docs/how-to-guides): Depending on your integration path, you'll need to access different parts of our docs.
- [OAuth overview](http://fullscript.dev/docs/how-to-guides/oauth/oauth-overview): When developing a Fullscript integration, your app’s Fullscript API interactions are done on behalf of Fullscript users.
- [Setup](http://fullscript.dev/docs/how-to-guides/oauth/using-oauth/setup): To get started with OAuth you you need your **App**’s client ID (client_id) and client secret (client_secret).
- [Request an auth code](http://fullscript.dev/docs/how-to-guides/oauth/using-oauth/request-auth-code): Once you've retrieved your app's client_id and client_secret, and set your app's OAuth scopes, the next thing to do is have a place in your app that triggers the user authorization process.
- [Request an access token](http://fullscript.dev/docs/how-to-guides/oauth/using-oauth/request-access-token): Now it's up to you to do the OAuth dance 🕺!
- [Refresh an access token](http://fullscript.dev/docs/how-to-guides/oauth/using-oauth/refresh-access-token): Once your app has a users's OAuth token, you should ensure it's unexpired before using it.
- [Revoke an access token](http://fullscript.dev/docs/how-to-guides/oauth/using-oauth/revoke-access-token): Since users granted your application access to their data via a process in your application, it's nice to also provide them a way to revoke access if needed.
- [What is Fullscript Embed?](http://fullscript.dev/docs/how-to-guides/fullscript-embed/what-is-fullscript-embed): Previously referred to as Fullscript.js, Fullscript Embed is our latest embeddable experience.
- [Important links](http://fullscript.dev/docs/how-to-guides/fullscript-embed/before-you-get-started/important-links): Here are the links you're most likely to use as you develop your Fullscript integration.
- [Development sandbox](http://fullscript.dev/docs/how-to-guides/fullscript-embed/before-you-get-started/development-sandbox): Development happens against our sandbox servers.
- [Design decisions](http://fullscript.dev/docs/how-to-guides/fullscript-embed/before-you-get-started/design-decisions): There are some common design questions that will come up as you work through your Fullscript integration.
- [Setup](http://fullscript.dev/docs/how-to-guides/fullscript-embed/using-fullscript-embed/setup): If you don’t already have an App created with Fullscript, sign in to the Fullscript API Dashboard and click **Create Application** (or continue to sign up if you’re brand new to us!).
- [OAuth and backend work](http://fullscript.dev/docs/how-to-guides/fullscript-embed/using-fullscript-embed/oauth-and-backend-work): By default, apps don’t have access to most functionality in the Fullscript API.
- [Add embeddable component](http://fullscript.dev/docs/how-to-guides/fullscript-embed/using-fullscript-embed/add-embeddable-component): Moving into the frontend work, let’s get Fullscript Embed installed.
- [Handle events](http://fullscript.dev/docs/how-to-guides/fullscript-embed/using-fullscript-embed/handle-events): Your integration could be considered complete now that you have the feature loaded on the page.
- [Go live](http://fullscript.dev/docs/how-to-guides/fullscript-embed/using-fullscript-embed/go-live): Before creating production versions of your applications and going live, there is a review and approval process of your sandbox application.
- [Error handling](http://fullscript.dev/docs/how-to-guides/fullscript-embed/reference/error-handling): If Fullscript Embed is not configured properly, or is attempting to access resources it’s not permitted to, an error page is rendered and the error details are sent to the browser’s console.
- [Events](http://fullscript.dev/docs/how-to-guides/fullscript-embed/reference/events): Here are the events each feature triggers.
- [Session grant endpoint](http://fullscript.dev/docs/how-to-guides/fullscript-embed/reference/session-grant-endpoint): id **string**
- [What is Fullscript Redirect?](http://fullscript.dev/docs/how-to-guides/fullscript-redirect/what-is-fullscript-redirect): For example, your app can include a “Create a Treatment Plan” button that opens a new browser tab to the patient’s record within the practitioner’s Fullscript account. Practitioners can search for and
- [Important links](http://fullscript.dev/docs/how-to-guides/fullscript-redirect/before-you-get-started/important-links): Here are the links you're most likely to use as you develop your Fullscript integration.
- [Development sandbox](http://fullscript.dev/docs/how-to-guides/fullscript-redirect/before-you-get-started/development-sandbox): Development happens against our sandbox servers.
- [Design decisions](http://fullscript.dev/docs/how-to-guides/fullscript-redirect/before-you-get-started/design-decisions): There are some common design questions that will come up as you work through your Fullscript integration.
- [Practitioner workflow planning](http://fullscript.dev/docs/how-to-guides/fullscript-redirect/using-fullscript-redirect/practitioner-workflow-planning): Typically, integrations with Fullscript Redirect use a flow similar to this:
- [Setup](http://fullscript.dev/docs/how-to-guides/fullscript-redirect/using-fullscript-redirect/setup): If you don’t already have an **App** created with Fullscript, sign in to the Fullscript API Dashboard and click **Create Application** (or continue to sign up if you’re brand new to us!).
- [OAuth for user authentication](http://fullscript.dev/docs/how-to-guides/fullscript-redirect/using-fullscript-redirect/oauth-for-user-authentication): By default, apps don’t have access to most functionality in the Fullscript API.
- [Treatment plan dynamic link](http://fullscript.dev/docs/how-to-guides/fullscript-redirect/using-fullscript-redirect/treatment-plan-dynamic-link): The secret sauce behind your Fullscript Redirect **“Recommend with Fullscript”** button is the dynamic link that you connect to it.
- [Other useful info from Fullscript](http://fullscript.dev/docs/how-to-guides/fullscript-redirect/using-fullscript-redirect/other-useful-info): Make your app stickier by giving patients and practitioners visibility into their Fullscript activities from your app.
- [Go live](http://fullscript.dev/docs/how-to-guides/fullscript-redirect/using-fullscript-redirect/go-live): Before creating production versions of your applications and going live, there is a review and approval process of your sandbox application.
- [What are webhooks?](http://fullscript.dev/docs/how-to-guides/webhooks/what-are-webhooks): If you’re unfamiliar with webhooks, they are a type of API where we push data to your app instead of you pulling it from Fullscript.
- [Subscribe to webhooks](http://fullscript.dev/docs/how-to-guides/webhooks/using-webhooks/subscribe-to-webhooks): Use the Fullscript API Dashboard to subscribe to webhooks.
- [Configure your application for webhooks](http://fullscript.dev/docs/how-to-guides/webhooks/using-webhooks/configure-your-app): When an event occurs, we start by making a request to your endpoint with an empty body. Configure your application to respond with either an HTTP 200 or HTTP 201 response that includes your secret cha
- [Webhook security](http://fullscript.dev/docs/how-to-guides/webhooks/using-webhooks/webhook-security): Once you have your basic endpoint and response working, augment it with an additional security step to know that the data payload is secure.
- [Missed and repeated webhooks](http://fullscript.dev/docs/how-to-guides/webhooks/using-webhooks/missed-and-repeated-webhooks): If your registered webhook receiving url isn’t accessible, we retry the notification up to 6 times with exponential backoff.
- [Troubleshooting webhooks](http://fullscript.dev/docs/how-to-guides/webhooks/using-webhooks/troubleshooting-webhooks): If you’re not receiving webhook events or aren’t getting notified all the events you expect, here are some things to check:
- [Order placed](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/order-placed): The order.placed webhook is triggered when a patient places an order via Fullscript.com.
- [Lab order updated](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/lab-order-updated): The lab_order.updated\* webhook event is triggered when:
- [Treatment plan created](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/treatment-plan-created): The treatment_plan.created webhook is triggered when a treatment plan is activated.
- [Treatment plan updated](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/treatment-plan-updated): The treatment_plan.updated webhook is triggered when an active treatment plan's status changes to "cancelled".
- [Treatment plan recommendation updated](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/treatment-plan-recommendation-updated): The treatment_plan.recommendation.updated webhook is triggered when an active treatment plan's details are changed.
- [Patient created](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/patient-created): The patient.created webhook is triggered when a new patient is created.
- [Patient updated](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/patient-updated): The patient.updated webhook is triggered when a patient is updated.
- [Patient emancipated](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/patient-emancipated): The patient.emancipated webhook is triggered when a dependent patient completes the emancipation process.
- [Product created](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/product-created): The product.created webhook is triggered when a new product is added to the Fullscript catalog.
- [Product description updated](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/product-desc-updated): The product.description.updated webhook is triggered when the description of a product in the Fullscript catalog changes.
- [Product  updated](http://fullscript.dev/docs/how-to-guides/webhooks/available-webhooks/product-updated): The product.updated webhook is triggered when a product in the Fullscript catalog is updated.
- [Events overview](http://fullscript.dev/docs/how-to-guides/events/events-overview): The Fullscript events endpoint that lets you request a list of recent events and pull details for each.
- [Labs overview](http://fullscript.dev/docs/how-to-guides/labs/labs-overview): Lab recommendations originate within a treatment plan and, when purchased by a patient, become lab orders. These orders contain one or more **lab tests**, each of which can produce individual **result
- [How to test labs](http://fullscript.dev/docs/how-to-guides/labs/how-to-test-labs)

## Key technical reference topics

- [Pagination](http://fullscript.dev/technical-reference/pagination)
- [OAuth](http://fullscript.dev/technical-reference/oauth)
- [Patients](http://fullscript.dev/technical-reference/patients)
- [Treatment plans](http://fullscript.dev/technical-reference/treatment-plans)
- [Webhooks](http://fullscript.dev/technical-reference/webhooks)
- [Events](http://fullscript.dev/technical-reference/events)
- [Orders](http://fullscript.dev/technical-reference/orders)

## API Dashboard

- [Sign up / registration](http://fullscript.dev/registration): Create a developer account
- [Applications](http://fullscript.dev/applications): Manage OAuth apps and API keys

## Optional

Copy-paste context for LLM sessions (also on the For AI page):

```markdown
# Fullscript API integration context

You are helping integrate with the Fullscript partner REST API and related products (Embed, Redirect).

## Sources (fetch these; prefer over HTML scraping)
- OpenAPI: https://us.fullscript.com/docs/api/open-api/v1/openapi.json
- Doc index: http://fullscript.dev/llms.txt
- Environments JSON: http://fullscript.dev/integration-environments.json
- Human docs: http://fullscript.dev/docs/getting-started/for-ai/overview

## Auth (OAuth 2.0 authorization code)
- client_id + client_secret from Fullscript API Dashboard
- Authorize (browser redirect, US sandbox): https://api-us-snd.fullscript.io/api/oauth/authorize
- Token (US sandbox): POST https://api-us-snd.fullscript.io/api/oauth/token
- API base (US sandbox): https://api-us-snd.fullscript.io/api
- Canada sandbox API base: https://api-ca-snd.fullscript.io/api
- API calls: Authorization: Bearer <access_token>
- Auth codes expire in 10 minutes; exchange via POST /oauth/token with grant_type authorization_code

## Integration options
- Fullscript Embed (@fullscript/fullscript-js) or Redirect (new tab) OR direct REST
- Webhooks: verify Fullscript-Signature HMAC header

## Do not use
- /api/dashboard/* routes (internal API Dashboard BFF only)
- Hosts from OpenAPI "localhost" servers entries (local dev only)
```